playwright-shard-balancer

A count-based split leaves one shard slower than the rest, and the run takes as long as that shard. With duration-balanced shards, every shard finishes at about the same time and the run takes the even split of the work.

• CI keeps npx playwright test --shard=k/n. Each shard reads the same timings file and computes the same plan through Playwright's preprocess reporter hook.
• A test costs the median of its last 5 passing durations, retries included.
• Tests in a file that is not in parallel mode stay together, and tests that share a lock go to one shard.
• It also scores Playwright's own split and keeps whichever plan finishes first.
• check fails the build when a test ran twice, ran nowhere, or did not run.

• Matches a brute-force optimum on every small suite in its tests, and reaches the lower bound on a 10,000-group suite in well under a second.

Node 22.5 or newer. Playwright 1.62 or newer for the reporter hook; plan writes --test-list files for Playwright 1.56 to 1.61.

Does it need an extra CI job?

No. Every shard computes the same plan from the same timings file.

What if the timings file is missing or broken?

It fails open: that shard run uses Playwright's built-in split. Strict mode fails the shard instead.

What happens on a pull request from a fork?

The cache is read-only, so restore cannot pin. It writes empty timings and every shard uses the built-in split.

How many shards do I need?

simulate replays your suite at any shard count, overhead included, before you change CI. With --target, it names the fewest shards that finish in time.

What turns balancing off by accident?

A --reporter flag on the command line replaces the config's reporters. Tests are keyed by project name, so every project needs a unique name.