how to parallelize playwright tests with sharding

TL;DR

Playwright shards the suite across machines with --shard=k/n, no coordinator needed. Split into as many shards as you have runners, keep shards balanced by timing, and merge the reports.

Error

(Not an error; a speed technique. Symptom: the Playwright job takes 45 minutes serially.)

Steps

1. Measure: run with --reporter=list and note total time. Expected: a baseline to beat.
2. Shard in CI: npx playwright test --shard=1/4, 2/4, 3/4, 4/4 across four jobs. Expected: each job runs a quarter of the specs.
3. Balance by time, not count: Playwright shards by file count by default; move slow specs so shards take similar time. Expected: no straggler shard.
4. Merge reports: use playwright merge-reports on the per-shard blob reports. Expected: one HTML report for the whole run.
5. Tune worker count per shard (--workers) to the runner's CPUs. Expected: no oversubscription.

When to use

• Serial runs exceed your CI time budget.
• You have parallel runners available.

When not to use

• Fewer than ~50 tests (overhead dominates).
• Tests share mutable state (sharding exposes the interference; fix the tests first).

Tool compatibility

• Playwright 1.30 through latest; --shard, merge-reports.

Variant phrasings

Playwright --shard example

The flag form; pair with a CI matrix.

Playwright parallel CI setup

The broader topic; sharding is the mechanism.

Why it happens

Playwright's test runner is shard-aware by design, unlike Cypress which needs an external coordinator. Sharding is the cheapest speedup available.

Edge cases

• Uneven shards waste the speedup; rebalance when you add slow specs.
• Blob reports must use --reporter=blob per shard for merging.
• Database-backed tests need isolated schemas per shard or they collide.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1RIVxorBvyE4rWqs3Mub9A