Playwright Test Sharding: How to Split Your Suite Across Multiple Machines

As a Playwright suite grows, running it sequentially on a single machine becomes a CI bottleneck. A suite that takes 30 minutes on one machine can run in 5–8 minutes when split across four. Playwright's built-in sharding makes this straightforward.

What Sharding Is

Sharding distributes your test suite across multiple machines, each running a portion of the tests in parallel. A shard is a numbered slice of the total test count. With four shards, each machine runs roughly one-quarter of the tests simultaneously, reducing total wall-clock time linearly with machine count.

This is different from Playwright's within-machine parallelism, which runs multiple tests concurrently on the same machine using worker processes. Sharding extends that to multiple machines. Both are complementary: a typical setup uses sharding across machines with 2–4 workers per machine.

How Playwright Sharding Works

Playwright distributes test files — not individual tests — across shards. Each shard is identified by its number and the total shard count. Run the first of four shards with:

npx playwright test --shard=1/4

The second machine runs --shard=2/4, and so on. Playwright's test runner handles the distribution. You do not need to manually assign tests to shards.

Because Playwright shards at the file level, the distribution is approximately even but not perfectly balanced if your test files have very different runtimes. For most suites this is fine. If you have a few very long test files, split them to improve balance.

Setting Up Sharding in CI

The most common setup is a matrix job in your CI system. In GitHub Actions, define a matrix with shard numbers 1 through N and pass the shard flag to the test command:

• Define a matrix strategy with shard indices
• Pass --shard=${ { matrix.shard }}/4 to your playwright test command
• Upload the HTML report from each shard as an artifact
• Merge reports in a final step if you need a combined view

GitLab CI, CircleCI, and other modern CI systems support the same pattern with their own matrix or parallel job syntax. The Playwright test command is identical across CI systems — only the matrix configuration changes.

Merging Reports from Multiple Shards

Each shard produces its own HTML report. To combine them into a single report, use Playwright's merge-reports command:

npx playwright merge-reports --reporter html ./all-blob-reports

The workflow: each shard uploads its blob report as a CI artifact, a final job downloads all blob reports into a single directory, and runs the merge command. The output is a single HTML report covering every test across all shards.

How Many Shards to Use

Start with fewer shards than you think you need. Each shard has a startup cost — cloning the repo, installing dependencies, installing browsers. If that overhead is 2 minutes and each shard only runs 3 minutes of tests, you are not gaining much.

A practical starting point for most suites:

• Under 100 tests: 2 shards
• 100–300 tests: 4 shards
• 300–500 tests: 6–8 shards
• 500+ tests: tune based on measurement

Measure the actual runtime after setup. If setup takes 90 seconds and the test run takes 2 minutes, adding a second shard drops total test time from 2 to 1 minute — but total CI machine-minutes doubles. Optimize based on developer feedback time, not raw machine time.

For more on running Playwright in CI, see How to run Playwright in CI/CD.