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

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

In parallel mode mocha loads your test files inside worker processes, and anything that assumes a single shared process breaks: global state, in-memory singletons, port collisions, and files that only run correctly when loaded once. The usual fix is to make each test file self-contained (its own setup/teardown, no cross-file globals) and to give workers distinct resources (ephemeral ports, isolated temp dirs). Start by running one failing file alone in parallel mode to isolate the culprit.

The query

mocha parallel mode tests failing: worker file issue

Use this when

• Tests pass with plain mocha but fail with mocha --parallel
• Workers crash or files report "file did not load" style errors
• You see port-in-use errors only in parallel runs
• Parallel runs are flaky while serial runs are stable

Not for

• Mocha installation or basic config problems
• Assertion failures that happen serially too
• Speeding up non-mocha runners

Steps

1. Run a single suspect file in parallel mode (npx mocha --parallel path/to/file.spec.js) and note the exact error. Expected output: the error reproduces with one file, proving it is a load/loading issue rather than cross-file interference.
2. Check the file's top-level code for process-global side effects: servers binding fixed ports, singleton DB connections, process.env mutation, or require cache assumptions. Expected output: you find at least one resource that cannot be safely duplicated across workers.
3. Make the file self-contained: bind ephemeral ports (port 0), create fresh clients per file, and move shared fixtures into before/after hooks instead of module top-level. Expected output: the single file passes in parallel mode.
4. Re-run the full suite in parallel and compare failures to the serial baseline. Expected output: parallel run is green, or remaining failures match the serial run (real bugs, not parallelism bugs).

Provenance

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

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

Thread query: mocha parallel mode tests failing: worker file issue

TL;DR: In parallel mode mocha loads your test files inside worker processes, and anything that assumes a single shared process breaks: global state, in-memory singletons, port collisions, and files that only run correctly when loaded once. The usual fix is to make each test file self-contained (its own setup/teardown, no cross-file globals) and to give workers distinct resources (ephemeral ports, isolated temp dirs). Start by running one failing file alone in parallel mode to isolate the culprit.

Not specified by the original author.

TL;DR

Give every spec its own setup in beforeEach: reseed the database or fixtures, clear storage, and use cy.session() for login so auth state is cached per session instead of leaking. Never rely on spec execution order; each spec must pass on its own.

The query

cypress multiple specs sharing state: how to isolate

Use this when

• specs pass alone but fail together
• test data from one spec appears in another
• login state leaks across specs

Not for

• flakiness within a single spec
• app bugs that only appear under load
• parallel-runner sharding issues

Steps

1. Run the failing spec alone to confirm it passes in isolation. Expected output: a green single-spec run, proving the leak comes from another spec.
2. Find the leaked state: database rows, localStorage, cookies, or files written by an earlier spec. Expected output: a concrete list of state that survives between specs.
3. Add a beforeEach that resets that state: a seed task, cy.clearCookies(), cy.clearLocalStorage(), or an API reset endpoint. Expected output: the reset runs before every test in the spec.
4. Replace repeated UI logins with cy.session() so login runs once per session and tests start from a clean page. Expected output: login happens once, cached across tests in the spec.
5. Run the full suite in different orders to confirm specs no longer depend on each other. Expected output: green runs regardless of spec order.

Provenance

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

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

Thread query: cypress multiple specs sharing state: how to isolate

TL;DR: Give every spec its own setup in beforeEach: reseed the database or fixtures, clear storage, and use cy.session() for login so auth state is cached per session instead of leaking. Never rely on spec execution order; each spec must pass on its own.