Migrate your test suite to Playwright

Who this is for

You settled the framework question already. The open one is the four years of tests sitting in the repository, and which of them survive the move.

• Enough tests that hand-converting them would come out of next quarter's roadmap.
• Test infrastructure with a single owner who would like to stop being it.
• A pass rate low enough that a red build gets re-run before anybody reads it.

We take a migration from any web automation framework, and a repository holding two of them at once is still one job. The three with pages of their own here are the ones we are asked for most often.

Changing framework does not have to mean changing language. Playwright ships four official bindings — TypeScript and JavaScript, Python, Java and .NET — and we deliver in all four, so a Java suite can arrive in Playwright still written in Java and your team can still read it. That choice reaches the pipeline. The sharding and the merged report shown further down belong to Playwright's own test runner, which ships only with the JavaScript and TypeScript binding, so a Java, Python or .NET suite is split and reported through the runner that language already has.

There is a size below which none of this is worth buying, and a suite one of your engineers could convert in-house is under it. A suite nobody trusted in the first place is a deletion rather than a migration, because moving it buys you a bad suite that runs faster. If there are no end-to-end tests at all, the engagement you want is a Playwright suite built from scratch. If the suite is already Playwright and nobody believes its results, that is flaky suite repair.

The code — where every migration lands

Conversion is engineers reading tests one at a time, and what each test becomes depends on the framework you are leaving. Every migration converges on a config file and a pipeline, so those are the two samples below.

The config is the whole runner, in one file a reader can hold in their head:

// 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 ? 2 : 0,
  reporter: process.env.CI ? 'blob' : 'html',
  use: {
    baseURL: 'https://staging.example.com',
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
      testIgnore: '**/quarantine/**',
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
      testIgnore: '**/quarantine/**',
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
      testIgnore: '**/quarantine/**',
    },
    {
      name: 'quarantine',
      use: { ...devices['Desktop Chrome'] },
      testMatch: '**/quarantine/**',
    },
  ],
});

Both samples on this page are written against Playwright 1.62.

The concurrency your old infrastructure needed a machine for is now two keys: fullyParallel and workers. The quarantine project is the migration-shaped part of the file. Converted tests that nobody trusts yet run under their own name and cannot redden the main job, which is what stops somebody deleting them in week three to get the build green. The webkit project runs Playwright's WebKit build, which is not Safari on an iPhone — that limit is below.

The pipeline is four commands, and they are the same four in GitHub Actions, GitLab CI or Jenkins:

# In each of four CI jobs, with SHARD set to 1, 2, 3 or 4.
npm ci
npx playwright install --with-deps
npx playwright test --shard=$SHARD/4

# In one job afterwards, with the four blob reports collected into one directory.
npx playwright merge-reports --reporter html ./all-blob-reports

Each job writes a blob report instead of an HTML one, and the last step merges the four into a single report for the run. Sharding balances differently depending on the config above: with fullyParallel set, the run is split at the level of individual tests, and without it at the level of files — which is why a suite of six long spec files spreads badly across four jobs until that key is on. Teams who would rather not install browsers on every run can start from the container image Playwright publishes for the release, which for 1.62 is mcr.microsoft.com/playwright:v1.62.0-noble in the CI documentation's own samples.

What it costs

The price is engineer time, and the only way to know it is to count the suite. 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.

On a migration it moves with how much of the suite is worth keeping, and with how much of its test data was set up by clicking through the product. A suite that signs in through the front end three hundred times is carrying three hundred conversions that are not really tests, and they cost the same as the ones that are.