Vitest isolate false cross-file module state cleanup boundary

Direct Answers

Does pool: 'forks' with singleFork: true expose module state to every test file in that process? Yes. All test files execute in a single Node process. The ES module registry and CommonJS require.cache are shared across every file. Top-level mutations, vi.mock registrations, and patched globals persist until explicitly cleared.

Is vi.restoreAllMocks() in afterEach enough to reset mocked modules before later files import them? No. vi.restoreAllMocks() only restores mock implementations (spyOn, fn, mock). It does not clear the module cache, so a later file importing the same module receives the already-mocked exports from the first file.

Where should per-file cleanup run so it completes before the next file's module graph resolves? In an afterAll hook at the end of each test file. This runs after the file's tests finish but before Vitest loads the next file in the same worker.

Why This Happens

With isolate: false, Vitest disables its default per-file module cache reset. The singleFork: true setting consolidates all files into one fork process, so the Node module registry becomes a single shared namespace. Vitest does not guarantee test file execution order under isolate: false, which means cleanup sequencing depends on the order files happen to run.

Minimal Cleanup Pattern

Add this to the end of every test file that creates mocks or mutates global state:

afterAll(() => {
  vi.resetModules();      // clears Vitest's internal module cache + Node's require.cache
  vi.restoreAllMocks();   // restores original implementations on spies/mocks
  vi.clearAllMocks();     // clears call history on remaining mocks
});

If you patch globals (e.g., Date, console, globalThis.fetch), add explicit restoration in the same afterAll:

afterAll(() => {
  vi.resetModules();
  vi.restoreAllMocks();
  vi.clearAllMocks();
  // Example: restore a globally patched Date
  if (global.__originalDate) global.Date = global.__originalDate;
});

What vi.resetModules() Does Not Fix

• Side effects already executed during module initialization (DB connections opened at top level, timers started, event listeners attached). These require explicit teardown in the same afterAll.
• Third-party singletons that cache internally (PrismaClient, Redis clients, etc.) unless they expose a reset method you call.
• ESM static imports hoisted before any afterAll runs. If file B imports a module mocked in file A, the mock must be established before file B's import — order dependency is unavoidable.

Order Dependency Workaround

Because Vitest doesn't guarantee file order with isolate: false, enforce a sequence by creating a single entry test file that imports others in a defined order, or run with --runInBand and a custom sequence script.

One Diagnostic Detail Needed

What Vitest version are you running? (npx vitest --version) Vitest 2.x changed internal module cache keys; vi.resetModules() behavior is version-sensitive. The exact cleanup reliability depends on your version.