Vitest `threads: true` global state leakage with `isolate: false`

Answer

Setting isolate: true in Vitest eliminates the non‑determinism caused by shared global state when threads: true is used.

Why the leakage happens (confirmed facts)

With threads: true and isolate: false Vitest re‑uses the same V8 context across worker threads. Top‑level module code runs once, so any variables, singletons, or side‑effects created at module scope are shared. Consequently, beforeAll/afterAll hooks defined in setup files and globals mutated in beforeEach/afterEach are visible to all workers, producing order‑dependent test results.

Likely explanation (based on observed behavior)

The non‑determinism appears as tests passing in isolation but failing when run in parallel because the shared state accumulates or is reset inconsistently across workers. Event‑loop timing and custom reporter instrumentation can exacerbate the issue but are not the root cause.

Steps to enable full isolation

1. Update vitest.config.ts (or vitest.config.js) to set isolate: true while keeping threads: true:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    threads: true,
    isolate: true,
    // optional: limit workers to CPU count
    // poolOptions: { threads: { isolated: true } }
  }
})

1. Ensure any global state you intend to share is explicitly re‑initialized in a beforeEach hook or moved to a dedicated fixture that is reset per test.
2. Run the test suite again; the previously flaky tests should now pass deterministically.

Performance trade‑offs of isolate: true

• Memory: each worker loads its own copy of the module graph, increasing RSS roughly proportional to the number of workers.
• Startup time: modules are parsed and executed per worker instead of being shared, adding a few seconds to test launch on large codebases.
• Throughput: after warm‑up, test execution speed is similar; the overhead is mainly paid once per worker.

Most vulnerable lifecycle hooks and globals

• Top‑level module code (variable declarations, singletons, side‑effects).
• beforeAll / afterAll hooks defined in setupFiles or within test files.
• Globals mutated in beforeEach / afterEach that are not reset per test (e.g., counters, caches, fake timers).

Can custom reporters distinguish test assertions from thread‑induced side‑effects?

No, unless the reporter runs exclusively in the main thread or snapshots the global state before each worker execution. A reporter that reads or writes shared globals cannot reliably tell whether a change originates from a test assertion or from another worker's leakage.

Missing diagnostic detail

If you are using a Node.js version older than v14.8, worker‑thread isolation may be incomplete; confirming your Node version would change the recommendation to upgrade Node before relying on isolate: true.