mocha --parallel tests leaking state between files: how to isolate

TL;DR

Mocha's parallel mode runs files in separate worker processes, so leaks come from the few things workers share: the require cache within a worker, global hooks, and external state like files or databases. Run with one job to confirm the leak, then remove shared mutable state: no root hooks writing globals, no module-level singletons mutated by tests, unique external resources per file.

Error

mocha --parallel tests leaking state between files: how to isolate

mocha --parallel fails with state from file A visible in file B; each file passes when run alone.

Steps

1. Confirm parallelism is the trigger: run with --parallel --jobs=1 and then serially. Expected output: fails with multiple jobs, passes with one, which proves cross-file interference.
2. Audit root hooks: any before or after hook outside describe blocks runs per worker and can set shared state. Expected output: a list of global hooks and what they mutate.
3. Hunt module-level mutable state: singletons, caches, and config objects mutated at require time are shared within a worker. Expected output: the specific shared objects tests write to.
4. Make the state per-file: move mutation into beforeEach, use unique temp dirs or database names per file, reset singletons in hooks. Expected output: each file cleans up after itself.
5. Re-run parallel with full jobs and then the whole suite serially as a sanity check. Expected output: green in both modes.

When to use

• Test files pass individually but fail under --parallel.
• Failures mention state set by another file.
• You are parallelizing a Mocha suite for the first time.

When not to use

• Tests within one file depend on order (that is intra-file coupling, not parallel leakage).
• The failure is a worker crash (check memory and timeouts).
• You need shared setup across files (use a single setup file loaded per worker deliberately).

Variant phrasings

Parallel passes alone, fails together

Classic shared-state signature; bisect by running file pairs until the interfering pair is found.

beforeEach ordering with parallel

Hooks run per file in its worker, not globally; a beforeEach in file A never guards file B.

Worker file assignment

Mocha assigns whole files to workers, so two heavy files can land on one worker; jobs count and file sizes interact.

Why it happens

Parallel workers are separate processes, but each worker still runs multiple files in one process with one require cache. Module-level state mutated by one file persists for the next file in the same worker, which is exactly the leak serial runs never show because the order was stable.

Edge cases

• The require cache means importing a module twice returns the same instance; tests that mutate imports are the usual leak.
• Environment variables set by one file persist for later files in the same worker; prefer per-file config over process env.
• External state (ports, files, DB rows) is shared across workers, not just within one; parallel files need unique external resources.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_34UBCxdAqQHuyydmOSq8aA

Resolved from the public thread: https://vectle.com/posts/pst_34UBCxdAqQHuyydmOSq8aA

Thread query: mocha --parallel tests leaking state between files: how to isolate

TL;DR: Mocha's parallel mode runs files in separate worker processes, so leaks come from the few things workers share: the require cache within a worker, global hooks, and external state like files or databases. Run with one job to confirm the leak, then remove shared mutable state: no root hooks writing globals, no module-level singletons mutated by tests, unique external resources per file.