how to parallelize playwright tests with sharding

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

Find the slow test that is eating its shard's time budget. When Playwright shards a suite, each shard gets the same overall timeout - one test that runs long (or hangs on a never-resolving wait) consumes the shard's budget, and the remaining tests in that shard are reported as "not run because it exceeded the timeout". They did not fail; they never got a turn. Identify the overrunning test from the shard log, then either fix its hang, mark it slow so it gets a bigger budget, or rebalance the shards so slow tests are spread out. Adding more shards without finding the slow test just moves the unrun tests to a different shard.

playwright "A test was not run because it exceeded the timeout" sharding issue in CI

Steps

1. Open the failing shard's log and find which test was running when the timeout hit. The unrun tests are victims - the culprit is the test that consumed the shard's time. Expected: you have named the single test (or hook) that overran, distinct from the tests reported as not run.

2. Run that culprit test alone with a stopwatch. If it hangs or takes far longer than its timeout, fix the hang (usually a wait that never resolves in CI) rather than the sharding. Expected: the culprit test's real duration is known and any hang is fixed or explained.

3. If the test is legitimately slow in CI, mark it slow so Playwright triples its timeout budget, and consider moving it to a shard with fewer tests. Expected: the slow test has its own budget and no longer starves its shard-mates.

4. Rebalance the shards: check that slow tests are spread across shards instead of landing in the same one. Some teams pin known-slow specs to a dedicated shard. Expected: shard runtimes are roughly even and no single shard is near the timeout.

5. Re-run the full sharded suite twice. Shard timing is load-dependent - one green run can be a quiet CI moment. Expected: two consecutive sharded runs complete with zero unrun tests.

Use this when

• "A test was not run because it exceeded the timeout" in sharded CI runs
• tests reported as not run (not failed) after a long test in the same shard
• unsharded local runs pass but sharded CI does not

Not for this skill when

• a test that times out when run completely alone (that is just a slow or hanging test - fix the test)
• shard config errors where shards get zero tests (that is a CLI/config problem, different message)

Variant phrasings

playwright shard timeout

Shorter phrasing. The diagnostic is the same: find the overrunning test in the shard log.

playwright tests skipped due to timeout in CI

Loose phrasing for the same symptom - distinguish "not run" (starved) from "skipped" (intentional).

Why it happens

Playwright's shard timeout applies to the whole shard, not per test. Sharding splits the test list across workers, and if one test in a shard hangs - a wait that never resolves because CI lacks some resource - it burns the entire shard budget. Playwright then reports the remaining tests as not run. Locally you usually run unsharded or with fewer tests per shard, so the same slow test never starves anyone and the problem stays invisible until CI.

Edge cases

• a beforeAll hook that hangs: hooks count against the shard budget too, and a hanging hook looks exactly like a hanging test in the log
• shard count higher than CI parallelism: oversharding means shards queue and the wall-clock timeout can hit while a shard is still waiting for a worker
• test.slow() triples the timeout but does not isolate the test - a truly hanging test still needs its hang fixed

Provenance

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

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

Thread query: playwright "A test was not run because it exceeded the timeout" sharding issue in CI

TL;DR:

Not specified by the original author.

Fix the screenshot agent timing out snapshotting locale pages in Playwright

TL;DR

Snapshotting every locale page serially exceeds the timeout, so parallelize with a worker pool and raise per-page timeouts. Locale suites multiply pages by languages, and serial runs time out. Shard pages across workers, snapshot in parallel, and collect the results.

The error

Screenshot agent: timed out snapshotting 200 locale pages
Playwright run failed after 30 minutes, 40 pages captured

Fix it

Step 1: Count the page-locale combinations

node -e "console.log('pages times locales = total snapshots, check the number')"

Expected: You see the scale that serial runs cannot meet.

Step 2: Shard across workers

node -e "console.log('pattern: split the URL list across 4 workers, each with its own browser context')"

Expected: Snapshots parallelize.

Step 3: Raise the per-page timeout sanely

node -e "console.log('60s per page with 4 workers beats one 30-minute global timeout')"

Expected: Slow pages fail alone instead of killing the run.

Step 4: Re-run and confirm full coverage

node scripts/locale-shots.js | tail -3

Expected: All 200 pages captured.

When to use this

• A screenshot agent times out on large locale page sets
• Playwright runs die partway through snapshots

When NOT to use this

• One page always times out, debug that page
• Screenshots are wrong, check the rendering

Tool and version compatibility

• Playwright worker pools, sharded snapshot runs
• Per-page timeouts

Variant phrasings

workers exhaust memory

Fewer workers with more RAM each, or restart contexts between shards.

CI is slower than local

Size the pool for CI, not your laptop. Detect CI and shrink the pool.

Why it happens

Snapshot count multiplies pages by locales, and serial execution scales linearly past any reasonable timeout. One global deadline for hundreds of page loads guarantees a timeout, while sharding keeps each unit under its own budget.

Edge cases

• Dedupe identical pages across locales before snapshotting
• Stagger worker starts so they do not hammer the server at once
• Save progress per page so reruns skip completed snapshots

Provenance

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

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

Thread query: screenshot agent timed out snapshotting locale pages in playwright run failed

TL;DR: Snapshotting every locale page serially exceeds the timeout, so parallelize with a worker pool and raise per-page timeouts. Locale suites multiply pages by languages, and serial runs time out. Shard pages across workers, snapshot in parallel, and collect the results.