Cypress to Playwright migration, custom commands included

What a converted spec looks like

An estimate gets built out of the conversions below. The Cypress in them is Cypress 15.21.1, and the version matters: most of the "Cypress cannot do that" lines still in circulation were true several majors ago and are not true now.

The chain that is not a promise chain

A Cypress spec and its Playwright equivalent rhyme. Here is the Cypress:

// cypress/e2e/customer-search.cy.ts
describe('customer search', () => {
  beforeEach(() => {
    cy.visit('/customers');
  });

  it('opens a customer from the results', () => {
    cy.get('[data-testid=search]').type('Ada Lovelace{enter}');
    cy.get('[data-testid=result]').first().click();
    cy.get('h1').should('contain', 'Ada Lovelace');
    cy.get('[data-testid=plan]').should('be.visible');
  });
});

And the same test in Playwright:

// tests/customer-search.spec.ts
import { test, expect } from '@playwright/test';

test.beforeEach(async ({ page }) => {
  await page.goto('/customers');
});

test('opens a customer from the results', async ({ page }) => {
  await page.getByTestId('search').fill('Ada Lovelace');
  await page.getByTestId('search').press('Enter');
  await page.getByTestId('result').first().click();

  await expect(page.getByRole('heading', { name: 'Ada Lovelace' })).toBeVisible();
  await expect(page.getByTestId('plan')).toBeVisible();
});

The Playwright samples on this page are written against Playwright 1.62.

The two files are about the same length and they do not run the same way. Cypress's own documentation is the clearest statement of the difference: commands "don't do anything at the moment they are invoked, but rather enqueue themselves to be run later", they "do not return their subjects, they yield them", and they "are not Promises and cannot be awaited". Playwright is ordinary async/await, and every action and every assertion above is a promise somebody has to wait on.

That difference produces two failures a mechanical conversion cannot see, and both leave the suite green. A dropped await compiles, runs and passes, because the assertion is evaluated against a page that has not settled. And plain JavaScript written between two commands ran in Cypress before the queue drained, while in Playwright it runs exactly where it sits: a counter, a read of a variable, a conditional.

The assertions change with them. Every .should('be.visible') in the suite becomes await expect(locator).toBeVisible(), and Playwright's assertions documentation says what that buys: "The following assertions will retry until the assertion passes, or the assertion timeout is reached." It is equally plain that non-retrying assertions "can lead to a flaky test". Where a converted assertion has no retrying form, expect.poll and expect.toPass are the escape hatches.

The waits that get deleted

The fixed sleep somebody added in a hurry is a deletion. The alias wait next to it is a translation:

// cypress/e2e/billing.cy.ts
describe('billing', () => {
  it('saves the plan', () => {
    cy.visit('/customers/42');
    cy.get('[data-testid=plan]').clear().type('enterprise');

    cy.intercept('PUT', '/api/customers/42').as('saveCustomer');
    cy.get('button[type="submit"]').click();
    cy.wait('@saveCustomer');
    cy.wait(2000);

    cy.contains('Saved').should('be.visible');
  });
});

In Playwright the sleep goes and the response wait moves in front of the click:

// tests/billing.spec.ts
import { test, expect } from '@playwright/test';

test('saves the plan', async ({ page }) => {
  await page.goto('/customers/42');
  await page.getByTestId('plan').fill('enterprise');

  const responsePromise = page.waitForResponse('**/api/customers/42');
  await page.getByRole('button', { name: 'Save' }).click();
  const response = await responsePromise;

  expect(response.ok()).toBeTruthy();
  await expect(page.getByText('Saved')).toBeVisible();
});

Setting the wait up before the action is the opposite of the reflex, and a converted suite that gets it round the wrong way waits for a response that has already arrived. Often the whole thing comes out: an auto-retrying assertion on the row that appears is a better test than a wait on the request that produced it. Not every alias wait is deletable, though. The ones asserting on the request or the response body become assertions on the response object, as above; deleting them silently removes coverage nobody notices is gone.

cy.intercept becomes page.route

The capability survives intact and the API changes. A stubbed empty state, in Cypress:

// cypress/e2e/customers-empty.cy.ts
describe('customer list', () => {
  it('shows an empty state', () => {
    cy.intercept('GET', '/api/customers', { fixture: 'customers-empty.json' }).as('getCustomers');
    cy.visit('/customers');
    cy.wait('@getCustomers');

    cy.contains('No customers yet').should('be.visible');
  });
});

And in Playwright:

// tests/customers-empty.spec.ts
import { test, expect } from '@playwright/test';

test('shows an empty state', async ({ page }) => {
  await page.route('**/api/customers', route => route.fulfill({ json: { data: [] } }));

  await page.goto('/customers');
  await expect(page.getByText('No customers yet')).toBeVisible();
});

The pass-through cases have counterparts too: route.abort() blocks a request, route.continue({ headers }) lets it through with something changed, and route.fetch() reads the real response so a test can modify it before it reaches the page. A route can also be registered on the browser context instead of on one page, so the intercept your suite repeats in every beforeEach usually collapses into a single fixture. page.routeFromHAR serves matching requests out of a recorded HAR file, which is one answer when your fixtures have drifted away from what the API actually returns.

A custom command becomes a fixture

A realistic command, registered the way custom commands are registered, with Cypress.Commands.add(name, callbackFn):

// cypress/support/commands.ts
Cypress.Commands.add('login', (email: string, password: string) => {
  cy.visit('/login');
  cy.get('[data-testid=email]').type(email);
  cy.get('[data-testid=password]').type(password);
  cy.get('button[type="submit"]').click();
  cy.get('[data-testid=account-menu]').should('be.visible');
});

In Playwright it becomes a fixture, which the specs request by name:

// tests/fixtures.ts
import { test as base, expect, type Page } from '@playwright/test';

type Fixtures = {
  signedIn: Page;
};

export const test = base.extend<Fixtures>({
  signedIn: async ({ page }, use) => {
    await page.goto('/login');
    await page.getByTestId('email').fill('ada@example.com');
    await page.getByTestId('password').fill('hunter2');
    await page.getByRole('button', { name: 'Sign in' }).click();
    await expect(page.getByTestId('account-menu')).toBeVisible();

    await use(page);

    await page.getByTestId('account-menu').click();
    await page.getByRole('menuitem', { name: 'Sign out' }).click();
  },
});

export { expect };

// tests/customers.spec.ts
import { test, expect } from './fixtures';

test('lists customers once signed in', async ({ signedIn }) => {
  await signedIn.goto('/customers');

  await expect(signedIn.getByRole('heading', { name: 'Customers' })).toBeVisible();
});

The code after await use(page) is the fixture's teardown half — Playwright's fixture documentation puts setup and teardown either side of that call — and it runs once the test is done with the fixture. A custom command has no such half, which is why cleanup in a Cypress suite tends to live in an afterEach a long way from the thing it cleans up. Scope is now a decision: a fixture runs per test by default, { scope: 'worker' } runs it once per worker process, and { auto: true } runs it whether a test asked for it or not, which is where a login that used to run on every single test stops doing that.

And not every command should become a fixture. Cypress's documentation gets there first — "Don't make everything a custom command", and "Can this be written as a function? The answer is usually yes." A migration that turns three hundred lines of commands into three hundred lines of fixtures has moved the problem into a new file. The ones that were only ever a function with a Cypress wrapper on it become functions.

cypress.config.ts becomes playwright.config.ts

Leaving Cypress means leaving a runner, so the config file is a deliverable in its own right. A Cypress config carries the runner's whole job:

// cypress.config.ts
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    baseUrl: 'https://staging.example.com',
    specPattern: 'cypress/e2e/**/*.cy.ts',
    supportFile: 'cypress/support/e2e.ts',
    retries: { runMode: 1, openMode: 0 },
    video: false,
  },
});

And the Playwright config that takes it over:

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  workers: process.env.CI ? 4 : undefined,
  retries: process.env.CI ? 1 : 0,
  reporter: [['html'], ['list']],
  use: {
    baseURL: 'https://staging.example.com',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

The supportFile line has no counterpart: what it loaded becomes fixtures the specs ask for by name and setup the config runs. Each entry under projects is a browser engine your suite now runs against, workers is the parallelism on one machine, and npx playwright test --shard=1/4 in four CI jobs runs a quarter of the suite in each. All of it is configuration in the open-source runner.

Two things called test isolation

A team that has tuned the Cypress option needs to know what it maps onto. Cypress resets the browser context before each test by visiting about:blank and clearing cookies, localStorage and sessionStorage across all domains; with it disabled, its documentation says "the page does not clear between tests and cookies, local storage and session storage will be available across tests in that suite." Playwright gets the same property from browser contexts instead of from an option: its documentation says "Playwright uses browser contexts to achieve Test Isolation", one context per test, and calls contexts "fast and cheap to create and are completely isolated, even when running in a single browser."

A suite that turned isolation off so a login would survive between tests has a dependency between those tests, and it has to be found and replaced, usually with stored authentication state, before any of those specs can be converted honestly. It is one of the few things in a Cypress repository that makes a small suite an expensive one.

What happens to the plugins

Your dependencies are plugins bolted into a runner, and the list in your package.json is the risk register for the whole job. Three buckets:

• Built into Playwright, so the plugin comes out. Network stubbing: page.route, route.fulfill, route.abort, route.continue and HAR replay, all above. Multiple tabs: Cypress's trade-offs page says you can test them "using our @cypress/puppeteer plugin", and Playwright's is "Each browser context can host multiple pages (tabs)", with context.newPage() and a page.waitForEvent('popup') promise held before the click that opens it.
• Built in, but the scope is a conversation. Component testing runs on the mount fixture that ships with @playwright/test, and the documentation points teams off the experimental @playwright/experimental-ct-react and @playwright/experimental-ct-vue packages onto it.
• Read one at a time, in the inventory. Accessibility, visual snapshots, BDD preprocessors, coverage, real events, tag filtering, uploads, reporters. Some are a swap and some are a rebuild, and we name a counterpart for a plugin after we have opened its documentation, not before.

What it costs

This is priced per engineer, because a conversion consumes engineer time. Engineers are billed hourly, from $50 an hour, depending on where the engineer sits. The minimum engagement is one full-time engineer for one month.

What you pay for a Cypress job moves with the number of spec files, how much of the suite lives in cypress/support instead of in the specs, how many plugins are in the repository and how many of those have no counterpart, how many pipelines run any of it, how much test data is set up by clicking through the UI, and whether the suite has state dependencies between tests. A suite of thin specs over a very thick commands.js takes longer to convert than its spec count suggests.