Split long test suites across runners

Distribute a suite across CI jobs while keeping complete test discovery and collecting the results from every shard.

Prompt

Evaluate and apply this CI technique to my repository: Split long test suites across runners.

Distribute a suite across CI jobs while keeping complete test discovery and collecting the results from every shard.

Read the technique and its source-backed company examples: https://starsling.dev/ci-playbooks/techniques/shard-test-suites.md

Inspect this repository’s CI workflows, build and test commands, dependencies, and recent run timings. Identify where this technique applies and explain the expected benefit using this repository’s evidence.
Measure a baseline from recent comparable runs: elapsed time, queue time, runner minutes and failures where available. If data is unavailable, say what cannot be measured.
Compare relevant company approaches, checking prerequisites, platform differences and tradeoffs. Rank applicable options by evidence, fit and measurable opportunity; do not present company results as predictions for this repo.
Recommend the smallest safe change, show what checks and fallback paths remain, and ASK ME WHICH CHANGE TO APPROVE BEFORE EDITING ANY FILES.
Only after approval, work on a new feature branch, make one reversible change, and open a reviewable pull request. Never merge or push to a default or protected branch.
Keep required checks, test coverage, deployment and release behavior intact. Validate the change and compare equivalent runs where possible; report limitations and what should be monitored after merge.

View all playbooks

How companies used this technique

Read what each company changed and follow the original sources.

Split test files across CI shards that stay balanced to within one file

Bun v1.3.13 added bun test --shard=M/N to split test files across CI runners, in the syntax Jest, Vitest and Playwright use. Files are sorted by path for determinism and distributed round-robin, so each shard stays balanced to within one file of the others. Inside one runner, bun test --parallel distributes files across worker processes, the CPU count by default, and idle workers steal work from the busiest remaining queue. Output stays identical to serial execution.

Split test files across multiple CI runners with the new --shard flag, matching the syntax used by Jest, Vitest, and Playwright. Source

Use it when: One test job runs a large suite on a single runner, and the suite can be split by file or run in more than one process.
Before applying it: Splitting by path balances file counts. Compare shard durations after the change, and move to duration-based splitting if one shard stays the long pole. Tests that share state need isolation before they run in parallel.

Shard the test phase across agents

Translated to GitHub Actions

What DoorDash built: DoorDash added sharding to Rush: a sharded operation becomes a pre-shard node, n shard nodes and a collate node that merges coverage.
Your GitHub Actions version: A test matrix of shards with each shard's index and its own output folder, followed by a job that merges coverage into one report.

DoorDash's tests already ran eight Jest workers per machine and had started to hit memory errors, so DoorDash added sharding to Rush upstream. A sharded operation becomes a pre-shard node that keeps the dependencies, n shard nodes, and a collate node that merges coverage into one report; each shard gets its index and its own output folder so the build cache stays valid. A follow-up clusters shards by operation name, so shards of one package can run on different agents. Four shards with seven workers each ran fastest, and every shard finished within six minutes, the same time as the build. DoorDash's Kotlin build service shards unit tests the same way.

All of the test shards completed within six minutes, which tied build time and test time. Source

Use it when: One test job runs long, or runs out of memory, after raising its worker count on one machine.
Before applying it: Every shard repeats setup, so pick the shard count by measurement, and collate coverage so the report still covers the whole suite.
GitHub Actions adaptation: Compare the source system with your own workflow before applying this translation.

Split a long end-to-end suite across runners

StarSling’s agent added three Playwright shards to the kitchen-sink job, passed each shard index to the test runner and kept fail-fast false.

Mastra’s kitchen-sink E2E suite still runs sharded today, now across four shards in e2e-tests.yml. Source

Use it when: A long test job remains the critical path after removing repeated waits and setup.
Before applying it: Each shard repeats setup and consumes runner minutes. Verify the union of tests, unique artifacts and required aggregate status.

Split the slowest job across runners

The CLI's help-compatibility workflow split its dispatch and contract tests into separate jobs on Intel macOS and Windows ARM, and moved an exhaustive flag-inventory test, which starts 482 subprocesses per platform, out of that matrix; the full Linux suite still runs it.

Workflow: 7m10s in the first successful run after merging current main, against the earlier 23-run median of 10m21s Source

Use it when: One job sets the workflow's finish time and its tests fall into independent groups.
Before applying it: Each split job repeats setup and adds runner minutes.

Give a long suite more than one runner

After measuring worker and shard combinations, the CLI raised Playwright's workers setting from 5 to 10 and added a two-shard matrix to its end-to-end job, giving each shard's artifacts a unique name. Each shard is a separate job that runs Playwright with the configured worker limit, so ten workers means up to ten on each machine. The default branch still runs two shards. The CLI's Windows unit tests are sharded the same way.

The PR reports ~4 min faster wall clock: 7m 44s against 11m 43s, a 34% reduction, comparing 10 workers on two shards with 5 workers on one runner. Source

Use it when: One test job is the longest in the workflow after its tests are isolated and its worker count is tuned.
Before applying it: Each shard repeats checkout, install and authentication, so total runner minutes can rise while elapsed time falls.

Shard a serial end-to-end suite across runners

The confidence-cli end-to-end suite runs serially because it uses a fixed auth callback port, and it took about 4.4 minutes of a 5.5-minute pull request run. The change splits it into four matrix shards with vitest --shard, each on its own runner, and adds an aggregate E2E tests job so the check name stays the same.

Before the change, E2E took about 4.4 minutes of a 5.5-minute pull request run; the author estimated about 1.5 minutes after it, with the slowest test file at 74 seconds as the floor (estimate). Source

Use it when: A test suite runs serially because its tests share a fixed resource on one machine, and it takes most of the pull request run.
Before applying it: Each shard repeats checkout and setup, and the slowest test file sets the floor for every shard.

Shard a long suite across runners

Stripe Android partitions discovered PaymentSheet end-to-end test classes across five parallel workflows. Stripe React Native split its end-to-end tests into matrix shards, and Stripe iOS shards full SDK size reports into three jobs on master and releases.

Use it when: One long test job remains the bottleneck after setup and worker tuning.
Before applying it: Each shard repeats setup. Verify the shards together run every original test exactly once, and keep device and diagnostic coverage.

How companies used this technique

Split test files across CI shards that stay balanced to within one file

Shard the test phase across agents

Split a long end-to-end suite across runners

Split the slowest job across runners

Give a long suite more than one runner

Shard a serial end-to-end suite across runners

Shard a long suite across runners

Related techniques

Balance test work across shards

Reduce the setup floor before increasing shard count

Split independent work off the longest job

Company Playbooks

Related guides

Shard tests across parallel jobs

Cut repeated test setup

Diagnose slow tests in CI

Optimize Playwright tests

Make Vitest run mode explicit

Parallelize independent jobs