Lorixen.
EN

Speed up a slow test suite by sharding it in CI

Short answer: If your test suite takes so long that developers stop waiting for it, split it across several CI machines running at the same time. Most test runners support sharding: Playwright and Jest both accept a --shard=1/4 style option, and CI systems such as GitHub Actions can start one job per shard with a matrix. Four shards don't make the pipeline exactly four times faster, because setup is repeated, but the wait usually drops sharply. Merge the reports afterwards so failures are still easy to read.

Why a slow suite is a business problem

A test suite that takes forty minutes changes how a team works. Developers batch changes to avoid waiting, merge without seeing results, or quietly skip tests. Fixes for urgent bugs sit in a queue. The tests still exist, but they protect less.

Speeding them up is often cheaper than it sounds. Before rewriting tests, check whether the work can simply run in parallel.

Two kinds of parallelism

Within one machine. Most runners already use several worker processes on a single machine. Jest has a --maxWorkers option to control how many; Playwright and pytest (with a plugin) do the same. If your CI machine has more cores than your runner is using, raising this is the quickest win.

Across machines (sharding). When one machine is maxed out, split the suite into chunks and give each chunk its own CI job. Playwright's documentation describes it directly: pass --shard=x/y, for example --shard=1/4 through --shard=4/4, and each run handles one quarter of the tests. Jest's command-line options include --shard in the same style.

Setting up shards in GitHub Actions

GitHub Actions uses a matrix strategy to run variations of a job. For sharding, the matrix is simply a list of shard numbers:

  1. Define a matrix with shard: [1, 2, 3, 4].
  2. In the test step, pass --shard=${{ matrix.shard }}/4 to your runner.
  3. Each value starts its own job on its own machine, at the same time.

Two matrix settings matter. fail-fast controls whether one failing shard cancels the others; for tests you usually want it off, so you see every failure in one run. max-parallel limits how many jobs run at once, which helps if you have a limited number of runners or a shared test database.

Other CI services, such as GitLab CI, CircleCI and Bitbucket Pipelines, offer equivalent parallel or matrix job features.

Getting one report back

With four shards you get four sets of results. Without merging, someone has to open each job to find failures. Playwright's guide recommends adding the blob reporter on CI, uploading each shard's blob report as an artifact, then running npx playwright merge-reports in a final job to produce one standard HTML report. Other runners can output JUnit XML, which most CI systems combine automatically in their test summary view.

Balancing the shards

Simple sharding splits by file or test count, not by duration. If one shard happens to get the slow checkout tests, it finishes last and sets the total time. Ways to even things out:

  • Split huge test files so slow tests can be spread around.
  • Use timing-based splitting if your runner or CI service supports it; some record durations from past runs and balance shards by time.
  • Check per-shard durations after a few runs, and adjust the shard count.

Watch for hidden dependencies

Sharding exposes tests that relied on running in a particular order or on shared state:

  • A test that only passes because an earlier test created a user record.
  • Two shards writing to the same test database rows at the same time.
  • Fixed ports or file paths that clash when tests run side by side on one machine.

Give each shard its own database or schema, generate unique test data (random emails, order numbers) and clean up after each test. These fixes also make the suite more reliable when run locally.

Don't forget the setup cost

Each shard repeats checkout, dependency installation, building and starting services. If setup takes eight minutes and tests take twenty, four shards give you roughly eight plus five, not five. To keep that overhead down:

  • Cache dependencies between runs.
  • Build once in an earlier job and share the build output with the test shards.
  • Use prebuilt container images with your tools installed.

More shards also mean more CI minutes in total, even if each run finishes sooner. Check your CI plan's usage before going from four shards to twenty.

Reproducing a shard failure locally

When one shard fails in CI, developers need to rerun exactly that chunk. Because sharding is deterministic for a given set of tests, running the same command locally, with the same shard number and total, reproduces the same selection. Add the command to your contributing notes, along with how to download the failing shard's report, traces or screenshots from the CI artifacts. That turns a red pipeline into a quick, local fix instead of a guessing game.

A worked example

Take a hypothetical Manchester online florist whose browser test suite had grown to around forty minutes as they added delivery-date and subscription scenarios. The team first raised the worker count on their CI machine, then split the Playwright suite into four shards with a GitHub Actions matrix, turned off fail-fast, and added a final job to merge blob reports into one HTML report. They gave each shard its own database schema after two tests started clashing. The pipeline now finishes in a fraction of the old time, and developers wait for it again.

FAQ

How many shards should I use?

Start with two to four and measure. Add more only while total wait keeps dropping meaningfully compared with the extra setup.

Will sharding fix flaky tests?

No. It often reveals more of them, because order and timing change. Fix the underlying shared state.

Can I shard unit tests too?

Yes, but unit tests are usually fast enough with in-machine workers. Sharding pays off most for browser and integration tests.

Do I need paid CI to do this?

Parallel jobs are available on many free and paid plans, with limits. Check your provider's concurrency limits.

If your team's test pipeline has become a bottleneck, tell us what it runs and how long it takes.

Sources

WhatsAppBook a call