Parallel Execution vs. --runInBand for Stateful Test Suites

Isolation Differences in Vitest Execution

The --runInBand flag provides a lower level of mock and state isolation compared to the default parallel worker pool. While parallel execution isolates test files across separate worker processes or threads, --runInBand executes all tests sequentially within the main process. This removes the process boundary, meaning global state mutations, modified prototypes, or mocks that are not explicitly cleared can leak from one test file into the next.

Parallel Workers vs. --runInBand

In default parallel mode, Vitest distributes files across workers. If two files are assigned to different workers, they are strictly isolated. If they share a worker, Vitest still attempts to isolate the environment, but the process boundary remains the primary defense against leakage. In contrast, --runInBand eliminates this boundary entirely to reduce the overhead of spawning workers.

When to use maxWorkers: 1 over --runInBand

You should prefer maxWorkers: 1 over --runInBand when your suite is stateful but still requires process-level isolation. Use maxWorkers: 1 under these specific constraints:

• Shared Resource Contention: Your tests interact with a single external resource (e.g., a local database or a specific file on disk) that cannot handle concurrent connections, but you still want to ensure that the memory state of one test file doesn't pollute another.
• Memory Leak Prevention: You are experiencing memory exhaustion in the main process and want the worker process to be recycled between runs.
• Strict Mock Isolation: You rely on the clean slate provided by a fresh worker process to ensure mocks from previous files are completely purged.

Verification Steps

To verify if state is leaking in your current configuration, you can run a scoped test:

1. Create test-a.spec.ts that modifies a global variable or a module-level singleton.
2. Create test-b.spec.ts that asserts the initial value of that same global variable.
3. Run with vitest --runInBand; if test-b fails, you have state leakage.
4. Run with vitest --maxWorkers=1; if test-b passes, the worker boundary is successfully isolating your suites.

Diagnostic Detail Needed: To provide a more precise recommendation, are you using threads or forks in your poolOptions? This changes how memory is shared and how isolation is enforced.