skip to content

In Node 24's built-in test runner, a suite passes with plain `node --test` but fails under `--test-isolation=none`. What explains it, and how do you find the culprit?

level: seniorimportance: should knowfreq 20%

answer

  1. one process per file, or one for all
  2. module cache and globals shared
  3. order dependence hidden by isolation
  4. a randomized order with a printed seed

basics

~20 s

By default each test file runs in its own child process, so module singletons, globals, process.env edits and top-level mocks die with the file; --test-isolation=none imports every file into one process, exposing tests that depend on shared state or order.

solid answer

~40 s

Plain `node --test` uses `--test-isolation=process`: each file runs in its own child process, up to `--test-concurrency` files at once, which defaults to `os.availableParallelism() - 1`. A file therefore starts with a fresh module cache, fresh globals and its own `process.env`. With `--test-isolation=none` every file is imported into the runner's process and top-level tests run one at a time, so a cached singleton, a patched global, an `env` change or a top-level `mock` that was never reset carries from one file into the next. To find the culprit, run the suspect files together in pairs, then use `--test-randomize` (Node 24.16.0 and later), which prints its seed, and replay the failing order with `--test-random-seed`. The fix is to make each test own its state with `t.mock`, `after` hooks and no module-level mutation.

code

bash · 8 lines
bash
# reproduce the shared-state failure in one process
node --test --test-isolation=none

# shuffle files and tests; the seed is printed as a diagnostic
node --test --test-randomize

# replay the exact order that failed
node --test --test-random-seed=12345

go deeper

for a junior

Recall that node --test runs each file in its own process by default, and that --test-isolation=none puts every file in one process.

for a middle

Explain what a fresh process gives each file, such as the module cache, globals and environment, and what --test-concurrency limits and what it leaves alone.

for a senior

Diagnose a suite that only passes under process isolation: name the shared-state sources, bisect by file, and use a printed random seed to replay the failing order.

for a principal

Decide whether a large suite runs in none mode for speed, and what CI guard, such as randomized runs or a second isolation mode, keeps it independent.

## Two execution models Node 24's runner, started with `node --test`, can run test files in two ways, chosen by **`--test-isolation`**: | | `process` (the default) | `none` | |---|---|---| | Where a file runs | Its own child process | Imported into the runner process | | Files at once | Up to `--test-concurrency`, default `os.availableParallelism() - 1` | One; `--test-concurrency` is ignored | | Module cache, globals, `process.env` | Fresh per file | Shared by every file | | `only` filtering | Needs `--test-only` | Works without the flag | | Startup cost | One Node process per file | One process in total | Under `process`, a file's verdict is its child's exit code, and anything the file did to its process disappears when that process exits. Under `none`, the runner loads every file first and then runs the top-level tests with a concurrency of one. The documentation warns about exactly this: tests from different files can interact, because state one file changes is visible to another. ## Why the suite breaks under `none` A suite that is green under process isolation and red without it has tests that depend on **state they do not own**. Process isolation was hiding it. The usual sources are: - **Module singletons.** A module evaluates once per process and its exports are cached. An in-memory store, a connection pool or a configuration object built at import time is shared by every file that imports it, so data one file writes is there when the next file reads. - **Patched globals.** A test that replaces `globalThis.fetch`, `Date` or a method on a builtin and never puts it back changes every later file. - **`process.env` changes.** One process has one environment, so a test that sets a variable for itself leaves it set for everyone after it. - **The top-level `mock` tracker.** Mocks made through the top-level `mock` export are not reset automatically, unlike those made through `t.mock`. - **Leftover listeners and handles.** `process.on(...)` handlers, open servers or intervals created by one file keep running while the others execute. None of this is specific to `none` mode. The same leaks already exist between tests **inside one file**, which share one process even under default isolation, and the test function's `concurrency` option defaults to `false` there, so those tests run one at a time in declaration order. A fixed order can mask a dependency just as process isolation does. ## Finding the culprit 1. **Narrow by file.** Run `node --test --test-isolation=none a.test.js b.test.js` on pairs until two files fail together; the earlier one leaves the state behind. 2. **Shuffle deliberately.** `--test-randomize`, added in Node 24.16.0, randomizes both the order of files and the queued tests within each file, and prints the seed it used, for example `Randomized test order seed: 12345`. `--test-random-seed=<n>` replays that order exactly and turns randomization on by itself. Neither flag works with `--watch` or `--test-rerun-failures`. 3. **Know the limit of shuffling.** Subtests awaited one by one with `await t.test(...)` keep their declaration order, because each starts only after the previous one ends; suites written with `describe()` and `it()` are shuffled. 4. **Confirm the fix both ways**: green under `none`, and green across several random seeds under the default. ## Fixing it - Create mocks with **`t.mock`**, whose tracker the runner resets after each test. - Close servers, pools and timers in an **`after()`** or **`afterEach()`** hook. - Save and restore any `process.env` key or global a test changes. - Move module-level mutable state behind a factory, so each test builds its own instance. - Do not reach for `--test-force-exit` to make a stuck file finish. It exits once all known tests are done even if the event loop would stay alive, which hides the open server or timer instead of closing it. - For a resource that really should be shared, such as one database started for the whole run, use an explicit fixture: a `before()` hook per file, or `--test-global-setup`, added in Node 24.0.0 and still early development, whose `globalSetup` and `globalTeardown` exports run once around all tests. ## Choosing a mode Process isolation is the safe default and lets files run in parallel. `none` saves a process start per file, which matters for suites with many small files, and it lets `only` filtering work without `--test-only`, but it gives up parallel files and needs a suite that is truly independent. Running the suite under both modes, or with randomization, in CI is a cheap way to keep it honest. Spreading files over several CI machines is a separate tool, `--test-shard=<index>/<total>`.

  • Under default `node --test`, a test marked `{ only: true }` runs alongside every other test, and the output carries a warning. Why?
    With process isolation, `only` filters only when the run is started with `--test-only`; otherwise the runner ignores the option and emits the diagnostic "'only' and 'runOnly' require the --test-only command-line option." With `--test-isolation=none` the flag is not needed. A forgotten `only` therefore narrows a run in one mode and not in the other.
  • Does `--test-concurrency` make the tests inside one file run in parallel?
    No. It caps how many test files run at once under process isolation. Inside a file, tests run on one thread, and the `concurrency` option of `test()` or `describe()`, default `false`, decides whether asynchronous tests overlap. Setting it to `true` lets them interleave on the same event loop, which is faster for I/O-bound tests but needs tests that share nothing.

  • With default isolation, tests in the same file cannot share state
  • --test-isolation=none runs all files in parallel in one process
  • --test-concurrency also sets how many tests inside a file run at once
  • A passing suite under process isolation proves the tests are independent
  • --test-shard randomizes order to catch order-dependent tests

Assumes Node 24: --test-isolation lost its --experimental- prefix in 23.6.0, and --test-randomize and --test-random-seed were added in 24.16.0.