Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js test concurrency

How the Node.js test runner runs things in parallel: the file-level --test-concurrency option, the per-suite concurrency option, isolation modes and shared state.

The Node.js test runner can run work in parallel at two separate levels, and they are controlled by different settings. Mixing them up is the most common source of confusion.

The first level is test files. By default node --test starts every test file in its own child process, and several of those processes can run at once. This is controlled by --test-concurrency on the command line and by the concurrency option of run(). The second level is tests inside one file. Within a file, tests and suites run one after another unless you give them a concurrency option. Both levels count how many things may run at the same time.

NODE
node --test --test-concurrency=4

Try it

Node.js Concurrency inside a suite

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Files in parallel are faster

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

File level:

NODE
node --test --test-concurrency=<n>
run({ files, concurrency: <boolean | number>, isolation: "process" | "none" })

Test and suite level:

NODE
test(name, { concurrency: <boolean | number> }, fn)
describe(name, { concurrency: <boolean | number> }, fn)
Setting Meaning
concurrency: false One at a time. This is the default for tests inside a file.
concurrency: true As many at once as the machine has available CPU parallelism (os.availableParallelism()).
concurrency: <n> At most n at once. A number of 1 is the same as false.
isolation: "process" Each test file runs in its own child process. This is the default.
isolation: "none" All files are loaded into the current process, one after another.

For test files, the default number of parallel processes is one less than the number of available CPUs (never fewer than one). --test-concurrency and run()'s concurrency apply only to files. They do not make tests inside one file parallel.

Edge cases. The concurrency option on a suite is inherited by the tests and suites inside it unless they set their own. A concurrent test must not rely on the order in which sibling tests finish, because with true the order follows the timing of the awaited work, as the first example shows. A test that is awaited on its own, such as a subtest, still runs normally; concurrency only matters when several siblings are pending together.

Usage notes

  • File-level parallelism is safe for tests that share nothing: each file has its own process, so module-level variables and the global object are separate. Files that share external resources (a database, a fixed TCP port, the same temporary file) can interfere. Use port 0 and unique temporary directories, or run those files with --test-concurrency=1.
  • With isolation: "none" (flag --test-isolation=none) files share one process, so they cannot run in parallel and global state leaks between them. It starts faster, but one file can break another.
  • Concurrency inside a suite helps when tests spend their time waiting (network, timers, files). CPU-bound tests gain nothing because JavaScript still runs on one thread per process.
  • Hooks follow the same rules. beforeEach and afterEach run around each test, and with concurrent tests they can overlap, so avoid shared mutable state in them.
  • The runner's output order is not the same as the finishing order of parallel files. Reporters group results so that one file's lines are kept together.
  • Keep unit tests that mutate shared fixtures serial and mark only the independent ones as concurrent.