Playwright Parallel Testing: Workers and Sharding Measured

What Is Playwright Parallel Testing?

Playwright parallel testing means running several tests at the same time in separate worker processes, each with its own browser and its own isolated context. It is the main lever available for cutting suite runtime, and it is controlled by two independent settings that get confused constantly: workers, which adds concurrency on one machine, and shards, which spread the test list across several machines.

Playwright runs tests in worker processes. Each worker is a separate operating-system process that owns a browser instance, and each test inside that worker gets a fresh browser context, which is an isolated profile with its own cookies, storage, and cache. Two tests running at the same time cannot see each other's browser state.

What varies is the unit being distributed. Out of the box Playwright parallelises across test files: a file is assigned to a worker, and the tests inside it run in declaration order on that one worker. Setting fullyParallel changes the unit from the file to the individual test, so any free worker can pick up any test.

That distinction decides whether the worker count does anything at all. A suite of three large spec files cannot use more than three workers under the default behaviour, however high you set the number. This is the most common reason a team raises the worker count, sees no improvement, and concludes that parallelism does not help their suite.

Parallel execution is not unique to Playwright, and the general tradeoffs are covered in what is parallel testing. What is specific here is that Playwright gives you two dials rather than one, and that they are frequently set as though they were the same dial.

Workers vs Shards

Workers and shards operate at different levels and multiply rather than compete. Four machines running two workers each gives eight tests in flight, exactly as one machine with eight workers does, but the failure modes and the cost are not the same.

The order matters. Saturating the machine you already pay for is free; adding machines is not. Teams that shard before measuring their worker curve routinely pay for four CI runners to do what six workers on one runner would have done.

Turning Parallelism On

Three settings cover almost every case. This is the configuration used for every number reported further down.

// playwright.config.js
module.exports = {
  testDir: './tests',

  // Distribute individual tests rather than whole files.
  // Without this, a suite of 3 spec files never uses more than 3 workers.
  fullyParallel: true,

  // Leave unset to accept the default: roughly half the available cores
  // locally, and half the reported cores in CI. Set it explicitly only
  // after measuring, and read it from the environment so CI can differ.
  workers: process.env.CI ? 4 : undefined,

  // Blob reports are the ones that can be merged after a sharded run.
  reporter: process.env.CI ? [['blob']] : [['list']],

  use: { headless: true },

  projects: [
    { name: 'chromium', use: { browserName: 'chromium' } },
  ],
};

Both dials can also be set per run, which is how you measure without editing the config between attempts:

# Change the worker count for one run
npx playwright test --workers=4

# Run one quarter of the tests, as CI job 2 of 4
npx playwright test --shard=2/4 --workers=2

# Merge the blob reports the shards produced
npx playwright merge-reports --reporter=html ./all-blob-reports

Playwright prints the worker count it settled on as the first line of every run, which is the fastest way to confirm that the setting took effect rather than being overridden somewhere:

Running 24 tests using 4 workers

  ✓   2 [chromium] › tests/bench.spec.js:8:3 › case 2 (1.4s)
  ✓   1 [chromium] › tests/bench.spec.js:8:3 › case 4 (1.4s)
  ✓   4 [chromium] › tests/bench.spec.js:8:3 › case 3 (1.4s)
  ✓   3 [chromium] › tests/bench.spec.js:8:3 › case 1 (1.4s)
  ✓   6 [chromium] › tests/bench.spec.js:8:3 › case 6 (1.2s)

  24 passed (8.1s)

The number before each test name is the worker index. Note that the tests do not complete in declaration order, which is the visible sign that distribution is actually happening.

Benchmark: 1 to 12 Workers

Method first, so the Playwright parallel testing numbers can be judged. The suite is 24 tests, each performing a page load, three interactions, two assertions, and a fixed one-second wait, which puts every test at roughly 1.2 to 1.4 seconds of work. The page under test is served from the local filesystem rather than over the network, deliberately: the goal is to measure how Playwright scales across workers, and network variance would bury that signal.

The machine is an Apple M3 with 8 CPU cores and 16 GB of memory, running macOS 26.5 and Playwright 1.62.1 against headless Chromium, with fullyParallel enabled. Each worker count was run twice, cold, with nothing else competing for the machine.

Every figure on this page comes from that setup, and the setup is stated so you can disagree with it. Published parallel-testing numbers are usually a customer anecdote with the suite size, the hardware, and the run count left out, which makes them impossible to check and impossible to compare against your own. The suite here is deliberately uniform, at roughly 1.2 to 1.4 seconds per test, because a suite with a wide spread of test durations measures the spread rather than the parallelism.

Three things in that table are worth acting on.

The first jump is nearly free. Going from 1 to 2 workers returned 97 percent of the theoretical doubling, which means a suite still running serially is leaving the largest single improvement on the table. If you change one setting today, change it from 1 to at least 2.

Efficiency then decays steadily rather than falling off a cliff. At 8 workers on 8 cores the suite ran 5.2 times faster, not 8 times. The missing 35 percent is browser startup paid once per worker, plus contention for CPU, memory bandwidth, and disk. That gap is normal, and a suite hitting it is correctly configured rather than broken.

Past the core count the curve flattens. Twelve workers on eight cores improved on eight workers by roughly half a second, a 9 percent gain for 50 percent more processes, each holding its own browser in memory. On a machine with less headroom that overcommitment is where runs start timing out under load, which surfaces as flakiness rather than as slowness and gets misdiagnosed accordingly.

Your absolute numbers will differ, because they depend on how much of each test is spent waiting on a network the CPU cannot help with. The shape of the curve is what transfers: strong early returns, a steady decay, and a flat section beyond the core count that is not worth paying for.

Sharding Measured

Sharding splits the test list into equal parts by count and gives each part to a separate run. This section measures what that is worth rather than walking through the setup, which is covered in depth in Playwright sharding. The same 24-test suite was split into four shards, each executed with 2 workers, which models four CI machines of modest size.

The shards were executed one after another on the same machine, so each figure is what that CI machine would spend on its own. The parallel row applies the rule that matters: when four jobs run at once, the run is finished when the slowest one is, so the wall clock is 4.3 seconds and not the 16.2 seconds of machine time consumed.

The comparison in the last two rows is the point. Four machines of two workers finished about a second ahead of one machine of eight workers, because two workers each sit comfortably inside their machine's cores while eight workers on eight cores are competing. The cost of that second was roughly 16 seconds of machine time against 5, a little over three times the compute. Sharding buys elapsed time with money, and that is a good trade only when the elapsed time is blocking a person or a deploy.

The other thing the table shows is the uneven-shard problem in miniature. Playwright splits by test count, not by test duration, so a shard that happens to receive the slow tests finishes last and every other machine idles waiting for it. Here the spread was 0.4 seconds. On a real suite with a mix of fast unit-style checks and slow end-to-end journeys, that spread is routinely the difference between a 6-minute and an 11-minute pipeline, and adding shards does nothing to fix it.

Why Parallel Breaks Tests

Playwright isolates the browser. It does not, and cannot, isolate anything on the other side of it. Every test that fails only under parallel execution is failing on state that lives outside the browser context, and the categories are predictable.

Playwright exposes the worker index for exactly this purpose, and reading it is usually the whole fix:

const { test, expect } = require('@playwright/test');

test('each worker uses its own account', async ({ page }, testInfo) => {
  // parallelIndex is stable for the life of the worker and unique across
  // the running workers, so account N belongs to worker N for this run.
  const user = `qa-user-${testInfo.parallelIndex}@example.com`;

  // Suffix anything you write, so two workers never collide on a name.
  const uploadName = `report-${testInfo.parallelIndex}-${Date.now()}.csv`;

  await page.goto('/login');
  await page.locator('#email').fill(user);
  // ...
  expect(uploadName).toContain(String(testInfo.parallelIndex));
});

There is a diagnostic worth knowing. If a suite passes at one worker and fails intermittently at four, the defect is in the tests, in shared data, or in the application's own concurrency handling. Reducing the worker count hides it; it does not remove it, and the third case is a genuine production bug that parallel testing just found for you.

Serial Blocks and Ordering

Some sequences genuinely cannot be parallelised, such as a multi-step wizard where each step depends on the previous one having completed. Playwright handles this per describe block rather than forcing the whole suite into one mode.

const { test } = require('@playwright/test');

test.describe('checkout wizard', () => {
  // These run on ONE worker, in declaration order. If step 2 fails,
  // step 3 is skipped rather than run against a broken state.
  test.describe.configure({ mode: 'serial' });

  test('step 1: add to cart', async ({ page }) => { /* ... */ });
  test('step 2: enter address', async ({ page }) => { /* ... */ });
  test('step 3: pay', async ({ page }) => { /* ... */ });
});

test.describe('account settings', () => {
  // Independent tests that may all fail without hiding each other.
  test.describe.configure({ mode: 'parallel' });

  test('change display name', async ({ page }) => { /* ... */ });
  test('change timezone', async ({ page }) => { /* ... */ });
});

Serial mode has a cost that is easy to miss: the block occupies one worker for its full duration, so a twelve-test serial block in a suite of forty becomes the floor on how fast the whole run can finish, regardless of worker count. Before reaching for it, check whether the dependency is real or whether the second test could simply create its own starting state through the API.

A serial block also changes what a failure means. Because later tests are skipped rather than run, one broken step reports as a single failure plus several skips, which reads very differently in a dashboard. If you rely on Playwright reporting to spot regressions, account for skipped tests in whatever you alert on.

Sharding in CI

A sharded pipeline has two stages: a matrix job that runs the shards, and a job that merges their reports. Skipping the second stage is the usual mistake, and it leaves you with four partial reports and no way to see the run as a whole.

# .github/workflows/playwright.yml
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false          # let every shard finish, so one failure
      matrix:                   # does not hide the others
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test --shard=${{ matrix.shard }}/4 --workers=2
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: blob-report-${{ matrix.shard }}
          path: blob-report
          retention-days: 1

  merge:
    if: ${{ !cancelled() }}
    needs: [test]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - uses: actions/download-artifact@v4
        with:
          path: all-blob-reports
          pattern: blob-report-*
          merge-multiple: true
      - run: npx playwright merge-reports --reporter=html ./all-blob-reports
      - uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report

Two details in that file do real work. Setting fail-fast to false stops a failure in shard one from cancelling the other three, which would otherwise leave you re-running the pipeline to find out whether anything else broke. And the merge job runs even when a shard failed, because a failed run is exactly when you want the combined report.

Pick the worker count per shard from the runner, not from your laptop. Standard hosted runners are small, and the CI default of half the reported cores is usually closer to right than any number chosen by hand. Measure one pipeline at two workers and one at four before committing to either.

What Parallelism Costs

Wall clock is the number teams optimise and machine time is the number they pay for. Those two move in opposite directions once sharding starts, and the benchmark above makes the trade explicit.

Read the last two rows together. Everything up to the core count is free: the machine is already paid for, and raising the worker count spends nothing. Past that point every further second of wall clock is bought with machine time, and the exchange rate is poor. Our four-shard run spent three times the compute for a 19 percent improvement.

That ratio is why the order of operations matters more than the tooling. Saturating one machine is the highest-return change available and it is the one teams skip, because adding CI runners is a configuration change while measuring a worker curve requires ten minutes of attention.

The exchange rate only justifies itself when the elapsed time is blocking a person or a deploy. A nightly regression run that nobody watches has no reason to be sharded; a pre-merge gate that thirty engineers wait on several times a day has every reason. Decide which one you are optimising before provisioning anything, because the same four runners are excellent value in one case and pure waste in the other.

Past the Local Ceiling

The benchmark shows where the local approach runs out. Worker scaling stops paying past the core count, and shard scaling means provisioning, warming, and paying for machines that sit idle between runs. Both problems get sharper the moment browser coverage enters, because running the suite on Chromium, Firefox, and WebKit multiplies the test count by three before any sharding decision is made.

The strategy that maps most directly onto Playwright sharding is auto-split on HyperExecute. Instead of you choosing a shard count and maintaining a CI matrix, a discovery command emits the list of test entities and the platform distributes them across the number of concurrent virtual machines you declare, each one an isolated environment where the tests run next to the browsers rather than across a hub-and-node hop. The HyperExecute documentation covers the discovery and concurrency configuration.

The practical difference is what happens when the suite grows. A hand-maintained shard matrix has a number in it that somebody has to remember to raise, and the uneven-shard spread grows quietly until a pipeline that used to take six minutes takes eleven. A declared concurrency against a discovered test list moves that decision out of the YAML matrix.

None of this replaces getting the local numbers right first. A suite with a twelve-test serial block or a shared login account will carry both problems onto any platform, and will scale about as badly there.

Choosing Your Numbers

Every Playwright parallel testing decision below comes down to one measurement, so run it rather than copying a worker count. It takes about ten minutes and the curve for your suite is the only one that matters:

for w in 1 2 4 6 8; do
  echo "workers=$w"
  npx playwright test --workers=$w 2>&1 | tail -1
done

Set fullyParallel to true before you start, or the numbers will describe your file layout rather than your worker count. Then read the output for the point where the next doubling stops returning a meaningful improvement, and set the worker count just below it. In our run that point sat at 8 on an 8-core machine; on a 4-core CI container it will sit lower.

Only reach for shards once that number is found and the run is still too slow. When you do, shard on duration rather than count if your reporting lets you: an even split by test count is not an even split by time, and the slowest shard is the only one whose duration you actually pay in wall clock.

If the ceiling turns out to be the machine rather than the configuration, running the same suite against cloud infrastructure removes the core count from the equation, and the Playwright testing documentation covers pointing an existing config at TestMu AI without rewriting the tests. Whichever direction you go, fix the shared-state problems from the table above first, because parallel infrastructure multiplies those failures rather than absorbing them.