How the balancer splits
Give it test durations, either a name,seconds list or test reports from a previous run, and a shard count. It sorts the items from longest to shortest and gives each one to the shard with the least time so far. This rule, longest processing time first, is a classic scheduling result: Graham proved in 1969 that its longest shard is never more than 4/3 of the best possible split, and in practice it lands within a few percent.
Next to it the balancer shows the split you get without timing data: consecutive chunks with the same number of tests each. When a few files are much slower than the rest, that split leaves one shard running long after the others have finished, and your CI job takes as long as its slowest shard.
The results:
If one file takes longer than a fair share, the balancer says so: that file sets the floor, and the fix is to split it, not to add shards.
Getting durations
From a report, drop JUnit, TRX, NUnit, Playwright JSON or CTRF files from a recent full run and choose what a shard gets: whole files, suites or classes, or single tests. Pick what your runner can actually shard.
| Runner | How it splits | What to balance |
|---|---|---|
| Playwright | npx playwright test --shard=1/4 splits by test file, or by single test when fullyParallel is on | Files, or single tests with fullyParallel |
| pytest with pytest-split | pytest --store-durations once, then pytest --splits 3 --group 1 on each shard | Single tests |
| CircleCI | circleci tests run (or circleci tests split on Server) with --split-by=timings, using timing data from the previous run's JUnit XML | Files or class names |
Playwright's own split does not use durations, so balanced shards there mean passing each shard its own list of files with --test-list, which the Copy button's one-path-per-line format fits. The sharded Playwright reports guide shows how to get one JSON report from a sharded run and wire the lists into a GitHub Actions matrix. pytest-split's least_duration algorithm uses the same idea as this page, assigning each test to the group with the least time so far, though it walks the tests in their own order rather than sorted longest first.
Sources
Get new posts by email.
Occasional email with new Testland posts and plugin releases.
Unsubscribe any time. Privacy policy