Sharding

04 04 Problem (🏁 solution)

To enable sharding, we need to change the way we run Vitest:

Provide the --shard option to the Vitest CLI, describing which shard group this process should run. For example, to run the first quarter of the tests, use --shard=1/4; the second quarter will be --shard=2/4, and so on.
Use --reporter=blob because it's required to support sharding.

These changes can be illustrated in a simple Bash script. Let's call it run-tests.sh:

npx vitest --reporter=blob --shard=1/4 & \
npx vitest --reporter=blob --shard=2/4 & \
npx vitest --reporter=blob --shard=3/4 & \
npx vitest --reporter=blob --shard=4/4 & \
wait

In this exercise, we are using a script to illustrate a sharded test run. On CI, you can put each individual npx vitest command from above into a separate job, splitting the entire test suite into multiple shards.

Then, to run all the tests I will run that script in my terminal:

./run-tests.sh

This script will split the test suite into four shards and run them in parallel (&), producing isolated test reports.

Sharding is particularly useful in CI. If you have a large test suite that takes 8s to complete, splitting it into four groups and four parallel CI jobs can speed up the tests up to four times.

Merging test reports

But since sharding splits our test suite, we need to glue it back together when previewing the results of the test run.

Use the --merge-reports flag in the Vitest CLI to merge multiple sharded test reports into one:

npx vitest run --merge-reports

This command will print the test summary as you're used to see from Vitest:

 ✓ src/two.test.ts (5000 tests) 2654ms
 ✓ src/one.test.ts (5000 tests) 2647ms

 Test Files  2 passed (2)
      Tests  10000 passed (10000)
   Start at  11:36:43
   Duration  24ms (transform 0ms, setup 0ms, collect 74ms, tests 5.30s, environment 0ms, prepare 138ms)

You can persist the .vitest-reports directory as an artifact between different jobs so you can generate the test summary once they are done.

Note that there's currently a bug in Vitest that displays the total test run incorrectly when merging reports.

Sharding in Vitest

04. Performance/04. Sharding (🏁 solution)

Sharding

Merging test reports

Related materials