Cypress 測試遷移至 Playwright 的逐步指南
Migrating from Cypress to Playwright: a step-by-step guide
這份逐步指南説明如何把 Cypress 測試遷移至 Playwright,建議逐個測試檔轉換,並在獨立 CI 工作中並行執行兩套測試。轉換時需處理 Playwright 動作的 await,以及兩個框架對斷言重試方式的差異。只有在 Playwright 測試穩定覆蓋相同行為後,才退役對應的 Cypress 測試;若元件測試佔比較高,指南建議遷移期間繼續留在 Cypress。
Originally published on the Momentic blog.
TL;DR
- Run Cypress and Playwright in separate CI jobs during the migration. Keep Cypress coverage until the converted specs pass reliably.
- Convert specs file by file, starting with tests that cover your most important user flows.
- Expect more work than a command-by-command rewrite. Cypress queues chained commands, while Playwright requires
await. Review assertions carefully because the frameworks retry them differently.
Cypress to Playwright command mapping
Use this table to translate common commands, then check the surrounding test logic. Playwright actions return promises, so the converted spec must await them.
| Cypress | Playwright | Migration note |
|---|---|---|
| cy.get('[data-testid="save"]') | page.locator('[data-testid="save"]') | Await the action on the locator, such as await locator.click(). |
| cy.intercept('GET', '/api/users', response) | await page.route('**/api/users', handler) | Register the route before the request starts. |
| cy.visit('/dashboard') | await page.goto('/dashboard') | Relative URLs require a configured baseURL. |
| cy.fixture('users.json') | Import JSON or expose data through a Playwright test fixture | A Playwright fixture supplies data to a test rather than queuing a command. |
| Cypress.Commands.add(...) | Playwright test fixtures or page-object helpers | Move shared setup into fixtures and reusable interactions into helpers. |
| cy.session('user', login) | test.use({ storageState: 'playwright/.auth/user.json' }) | Create the authenticated state first. storageState does not preserve sessionStorage. |
| .should('be.visible') | await expect(locator).toBeVisible() | Use a Playwright assertion so the condition retries until its timeout. |
A route handler needs to fulfill or continue the request. For example, this Playwright test registers a stub before opening the page.
import { test, expect } from '@playwright/test';
test('shows the account name', async ({ page }) => {
await page.route('**/api/account', async (route) => {
await route.fulfill({ json: { name: 'Ada' } });
});
await page.goto('http://localhost:3000/account');
await expect(page.getByText('Ada')).toBeVisible();
});
The example assumes your app serves /account locally and requests /api/account. Replace those paths with your app’s routes.
The async model change: chained commands vs await
Cypress queues commands and retries queries and assertions, so a chain can wait for the page to reach the expected state. Playwright runs asynchronous actions in sequence only when you await them. Its actions wait for conditions such as visibility and readiness to receive a click, while expect assertions retry until they pass or time out.
With a base URL configured, the same search test looks like this in Cypress.
it('shows search results', () => {
cy.visit('/search')
cy.get('input[name="query"]').click().type('invoice')
cy.get('button[type="submit"]').click()
cy.get('#status').should('have.text', 'Results for invoice')
})
In Playwright, fill() replaces the input value, and each action and assertion needs await.
import { test, expect } from '@playwright/test'
test('shows search results', async ({ page }) => {
await page.goto('/search')
await page.locator('input[name="query"]').click()
await page.locator('input[name="query"]').fill('invoice')
await page.locator('button[type="submit"]').click()
await expect(page.locator('#status')).toHaveText('Results for invoice')
})
A mechanical replacement can leave promises unhandled. If you omit await before click(), the test may start typing before the click finishes, causing a race condition. Replacing should('have.text', ...) with a one-time textContent() check creates a different problem. The check can read the old DOM before the result appears, while await expect(locator).toHaveText(...) keeps checking within its timeout.
Step-by-step migration
Migrating file by file lets you compare the new Playwright suite with the Cypress suite before removing either one. Start with a spec that covers an important user path, then carry its behavior, authentication, and CI checks across.
1. Install Playwright alongside Cypress
Keep Cypress installed while you port specs. Add Playwright and its browser binaries without changing the existing Cypress scripts.
npm install --save-dev @playwright/test
npx playwright install
Put new specs in tests/playwright so Playwright does not discover Cypress files. Commit the Playwright dependency and configuration before converting tests.
2. Port the base URL and environment values
Create playwright.config.ts. Playwright reads environment variables through process.env, so replace Cypress.env('NAME') references with the corresponding process.env.NAME references as you convert each spec.
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests/playwright',
use: {
baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
trace: 'retain-on-failure',
},
});
The example assumes your app runs on port 3000. Start it before running either suite, or set BASE_URL to the address your CI job uses. Keep secrets in CI environment variables rather than committing them to the config.
3. Convert one spec end to end
Port the interaction and its assertion together. A Cypress chain queues commands, while a Playwright test must await browser actions and assertions. Leaving out an await can let the test finish before the browser completes the action.
// Cypress
describe('product search', () => {
it('shows matching results', () => {
cy.visit('/products');
cy.get('[data-testid="search"]').type('keyboard');
cy.get('[data-testid="results"]')
.should('contain.text', 'keyboard');
});
});
// tests/playwright/products.spec.ts
import { test, expect } from '@playwright/test';
test('product search shows matching results', async ({ page }) => {
await page.goto('/products');
await page.getByTestId('search').fill('keyboard');
await expect(page.getByTestId('results')).toContainText('keyboard');
});
Run the new spec against the same app as its Cypress counterpart.
npx playwright test tests/playwright/products.spec.ts
Replace selectors when the existing ones depend on fragile DOM structure. Playwright's locator guide covers the available locator strategies. In this example, toContainText retries the assertion while results load. A one-time read of textContent() would not provide that retry behavior.
4. Convert custom commands into explicit helpers or fixtures
Move a custom command's implementation when you move the specs that call it. A small command can become a helper that accepts page, making its browser dependency visible at the call site.
// tests/playwright/helpers/catalog.ts
import type { Page } from '@playwright/test';
export async function openCatalog(page: Page) {
await page.goto('/products');
}
import { openCatalog } from './helpers/catalog';
await openCatalog(page);
Use a Playwright fixture when the replacement must prepare state for many tests, and use a page object when several tests share interactions with the same page. Do not translate a custom command mechanically if it also hides network stubs or test data setup. Port those effects explicitly and check the resulting behavior.
5. Replace cy.session() with saved authentication state
Playwright can save cookies and local storage after login, then load that state in authenticated specs. Create a setup test using your application's actual login fields and success condition.
// tests/playwright/auth.setup.ts
import { test, expect } from '@playwright/test';
test('save authenticated state', async ({ page }) => {
await page.goto('/login');
await page.getByLabel('Email').fill(process.env.E2E_EMAIL!);
await page.getByLabel('Password').fill(process.env.E2E_PASSWORD!);
await page.getByRole('button', { name: 'Sign in' }).click();
await expect(page).toHaveURL(/\/dashboard/);
await page.context().storageState({
path: 'playwright/.auth/user.json',
});
});
Create the directory, run setup, and load the file only in specs that need authentication.
mkdir -p playwright/.auth
npx playwright test tests/playwright/auth.setup.ts
// At the top of an authenticated spec
import { test, expect } from '@playwright/test';
test.use({ storageState: 'playwright/.auth/user.json' });
Add /playwright/.auth/ to .gitignore. Run the setup test before authenticated specs in CI, and regenerate the file when the session expires. Saved state does not reproduce every cy.session() callback, so retain any test-specific setup separately.
6. Run both suites in CI until coverage matches
Give Cypress and Playwright separate CI jobs against the same app build. The Playwright job needs browser installation and, if it runs authenticated specs, the authentication setup before the suite.
# Cypress job
npx cypress run
# Playwright job, after starting the app
npx playwright install
mkdir -p playwright/.auth
npx playwright test tests/playwright/auth.setup.ts
npx playwright test
Exclude auth.setup.ts from the main Playwright run or configure it as a setup project, so it does not run again as an ordinary spec. Keep both jobs required while you compare the user paths and assertions they cover. Retire a Cypress spec after its Playwright replacement checks the same behavior, rather than after a fixed migration date. The Playwright CI/CD guide covers pipeline configuration in more detail.
What breaks when you migrate
Cypress assertions can pass while a direct Playwright translation flakes because the two frameworks retry different operations. Cypress retries a query and its chained assertion until the condition passes or times out. Playwright retries web-first assertions such as toHaveText, but expect(await locator.textContent()).toBe('Ready') compares one value captured at one moment. Use await expect(locator).toHaveText('Ready') for DOM state, or expect.poll when the value comes from a function rather than a locator. Playwright’s action auto-waiting does not make a later one-shot assertion retry.
Iframe selectors need to start inside the frame. A Cypress test that reads an iframe’s document cannot replace cy.get with page.locator, because the page locator searches the parent document. Use frameLocator to reach the element, then apply a web-first assertion.
const checkout = page.frameLocator('iframe[name="checkout"]')
await expect(checkout.getByRole('button', { name: 'Pay' })).toBeVisible()
Component tests need a separate migration decision. Playwright’s component testing is experimental, and Cypress mount helpers and their custom commands do not translate directly into Playwright component tests. If component tests make up a substantial part of your suite, keep them in Cypress while you migrate end-to-end specs. Evaluate Playwright’s component testing against your components and test helpers before retiring that suite.
Running both suites during the migration
Run Cypress and Playwright in separate CI jobs while you port specs. A hard cutover removes regression checks for behavior the new suite has not covered yet. During the overlap, keep the Cypress job required and add the Playwright job so you can investigate failures without losing the existing check.
Both jobs should test the same commit against a comparable application environment. Give each job its own server process and port, or use separate test environments if they run concurrently. Keep framework-specific config, environment variables, and test artifacts separate so one job cannot overwrite the other’s results.
Port specs in small batches and compare the behavior each suite verifies, not just the number of passing tests. Retire a Cypress spec when its Playwright replacement covers the same assertions and relevant browser configuration, and the new job runs reliably in CI. Remove the Cypress job only after the remaining Cypress coverage has a replacement or an explicit reason to drop it.
CI example: running Playwright in the pipeline
Run Playwright in its own CI job while Cypress remains active. The job below installs the project’s locked dependencies and Playwright browsers, then uploads the HTML report and retained traces if a test fails.
name: Playwright
on:
push:
pull_request:
jobs:
playwright:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test --trace retain-on-failure --reporter=html
- uses: actions/upload-artifact@v4
if: ${{ failure() }}
with:
name: playwright-failures
path: |
playwright-report/
test-results/
if-no-files-found: ignore
The test command assumes your Playwright config starts the application through webServer or points tests at an accessible environment. Keep the Cypress job separate so a Playwright failure cannot hide a Cypress failure during the migration. For deployment environments and other pipeline patterns, see the Playwright CI/CD guide .
How long migrating 500 tests actually takes
A 500-test count cannot produce a credible migration time estimate on its own. A suite with shared custom commands and stable selectors takes different work than one with duplicated setup and flaky tests. Use a representative pilot to measure each path before committing to a deadline.
| Path | Planning estimate for 500 tests | What to measure in the pilot |
|---|---|---|
| Manual engineering | Pilot hours per converted test × 500, plus shared setup and CI work | Time spent replacing custom commands, debugging flakes, and reviewing coverage |
| Coding agent | Pilot review and repair hours per converted test × 500, plus shared setup and CI work | How often generated tests need corrections, especially around custom commands and existing flakes |
| Momentic | Depends on how many user journeys the suite covers; there is no syntax conversion step | Time to express the existing suite’s intent, have agents author and run tests, review repairs, and verify coverage |
The manual and coding-agent estimates depend heavily on custom command density and existing flake, not test count alone. For either path, sample simple and complex specs so one easy file does not set the schedule for the whole suite.
Momentic’s path is a separate evaluation, not a faster syntax conversion. Its agents can author, run, and repair tests based on the behavior you want to verify, but you still need to check that the new tests cover the old suite’s important assertions.
Where Momentic fits after the migration
Playwright changes how you write and run browser tests, but you still own selector upkeep, flaky-test triage, and decisions about which behavior needs coverage. Keep those responsibilities visible after the Cypress suite retires.
If you add Momentic as a verification layer beside Playwright, define which user behaviors each suite checks and review failures for useful signal. Keep existing Playwright tests until any replacement checks have demonstrated equivalent coverage. Engineers still weighing the framework choice can read Cypress alternatives and Playwright vs. Cypress .
To evaluate Momentic against your migrated suite, sign up .
Frequently asked questions
Can Cypress and Playwright coexist in one repo long-term?
Yes. Keep their configs and test directories separate, and run each suite in its own CI job. You will maintain two sets of dependencies and test infrastructure for as long as both remain.
What happens to Cypress plugins without a Playwright equivalent?
Identify what each plugin does before replacing it. A plugin that creates test data may become a Node helper, while a plugin that changes browser behavior may require a different approach.
Does the TypeScript config need to change?
Not necessarily. If Cypress and Playwright types conflict, give each suite its own tsconfig.json with separate test-file includes.
How should I replace arbitrary cy.wait() timeouts?
Wait for the condition the test needs, such as a visible element with expect(locator).toBeVisible() or a specific response with page.waitForResponse(). A fixed delay can expire before the condition is ready or waste time after it is ready.
來源:DEV Community · dev.to