Jest test concurrency

Worker pool

By default Jest executes its tests in a pool of child processes that run the jest-worker package.

You can install and run the jest-worker package, to have a deeper control of the processes.

If on Node >= v22.9.0, then you may consider using the new, experimental native worker threads.See section on experiental worker threads in jest-worker.

The number of workers to be run is defined by this file in the source for the jest-config package.

It's essentially:

• Exactly 1 if --runInBand is provided
• Exactly N if --maxWorkers=N is provided
• A percentage of CPU cores if --maxWorkers=N% is provided. (Like --maxWorkers=80% for 80% of the cores as workers)
• If nothing is provided, max CPUs minus 1 for non-watch mode, and 50% CPUs for watch mode.

Sharding

Tests can be broken into distinct groups by using the builtin sharding.

To run a test suite with sharding, provide the --shard=A/B argument, where:

• A is the shard number to be run
• B is the total number of shards

Like:

# Split into three shards
npx jest --shard=1/3
npx jest --shard=2/3
npx jest --shard=3/3

See the documentation on the --shard argument

Test sequencers

How the tests are ordered and how the shards are split and sequenced depends on your TestSequencer. A test sequencer is a class which extends @jest/test-sequencers Sequencer base class.

It can be configured with a path to the file which provides a CJS export of the sequencer, like:

/** @type {import('jest').Config} */
const config = {
  testSequencer: "path/to/custom-sequencer.js",
};

module.exports = config;

The default test sequencer source can be found here under jest-test-sequencer.

Concurrency

Tests can be marked to run concurrently using it.concurrent() (or test.concurrent(), aliases).

Current issues

Concurrent tests do not currently support beforeEach(), afterEach() or expect.assertions. See here for the Jest tracker for concurrency-specific issues.

Test cases being run concurrently must be asynchronous.

test.concurrent("addition of 2 numbers", async () => {
  expect(5 + 3).toBe(8);
});

This can also be used with .each(), like:

test.concurrent.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])(".add(%i, %i)", async (a, b, expected) => {
  expect(a + b).toBe(expected);
});