How Playwright parallelises tests
Playwright runs tests across multiple worker processes by default. Each worker gets its own browser context, which means cookies, localStorage, and session state are isolated between workers automatically. Tests within a single file run sequentially by default; tests across files run in parallel.
The number of workers defaults to half the number of CPU cores on the machine. On a local developer machine with 8 cores, you get 4 workers. On a CI machine with 2 cores, you get 1. This is why suites that run fast locally can be slow on CI.
- workers: 4 in playwright.config.ts sets a fixed worker count
- fullyParallel: true makes tests within a file also run in parallel
- Workers are isolated browser processes — no shared browser state
- Test ordering within a worker is deterministic; across workers it is not
Sharding across machines
For large suites, running all workers on a single machine hits a ceiling. Playwright's sharding feature splits the test suite across multiple machines. Each machine runs a slice (shard) of the total tests, and results are merged at the end.
In a GitHub Actions matrix, you can run 4 shards in parallel with --shard=1/4, --shard=2/4, etc. A 20-minute suite on one machine becomes a 5-minute suite across 4. The playwright merge-reports command combines the results into a single report.
- npx playwright test --shard=1/4 runs the first quarter of tests
- GitHub Actions matrix strategy makes multi-machine sharding straightforward
- Playwright's blob reporter captures results per shard for later merging
- Sharding is orthogonal to workers — you can use both
State isolation in parallel runs
The most common parallel testing failure is shared database state. Two tests that both create a user with the same email address will conflict. Two tests that both modify the same record will produce unpredictable results depending on execution order.
The fix is test-specific state: each test creates its own unique resources (unique email addresses, unique order IDs) and cleans up after itself. Playwright's beforeEach and afterEach hooks, combined with unique identifiers (a timestamp or UUID in the test data), keep tests isolated regardless of execution order.
FAQ
How do I make Playwright tests run faster?
Increase the worker count to match your CI machine's CPU cores, enable fullyParallel mode, and use sharding across multiple machines for large suites. Beyond configuration, eliminating unnecessary waitForTimeout calls and using Playwright's network mocking for slow third-party dependencies also reduces runtime significantly.
Can Playwright tests run in parallel on a single machine?
Yes. Playwright's default behaviour is to parallelise across files using multiple worker processes. You can increase the worker count in playwright.config.ts. For tests within a single file to run in parallel, set fullyParallel: true — but ensure tests are fully state-isolated before doing so.
What is test sharding in Playwright?
Sharding splits your test suite into N equal slices that can run on N separate machines simultaneously. Each machine runs one shard with the --shard=X/N flag. Results are merged afterwards. It is the primary technique for scaling Playwright suites beyond what a single machine can handle.
Put the workflow in your repo, not in a chat transcript
Assert is strongest when scenarios become durable project assets: readable Markdown in the repo, generated execution underneath, and result inspection in the dashboard.