Worker Thread Pool Isolation: How Tinypool & Worker Threads Execute Tests in Parallel

Parallel test execution requires strict state isolation. If Test Suite A mutates a global variable or DOM node while Test Suite B reads it, test runs become non-deterministic.

Vitest solves this by running test files inside isolated worker threads or child processes using tinypool, a lightweight fork of piscina.

// Vitest pool configuration in vitest.config.ts
export default defineConfig({
  test: {
    pool: 'threads', // 'threads' | 'forks' | 'vmThreads'
    poolOptions: {
      threads: {
        maxThreads: 8,
        minThreads: 2,
        isolate: true,
      },
    },
  },
});

Comparing Execution Pools: Threads vs Forks vs vmThreads

Vitest offers three execution pools depending on your isolation requirements:

1. threads (Node worker_threads)

• Default: Shares Node’s process memory space but runs V8 contexts isolated per worker thread.
• Speed: Extremely fast startup times (~15ms overhead per thread).
• Trade-off: Native C++ Node modules (like better-sqlite3 or canvas) must be worker-thread safe.

2. forks (Child Processes via child_process.fork)

• Isolation: Complete process-level isolation with separate memory spaces and environment variables.
• Speed: Slower startup overhead (~100ms per process).
• Use Case: Necessary when testing native C++ modules or code that mutates process.env globally.

3. vmThreads (V8 Context Isolation within Threads)

• Isolation: Runs test files inside separate V8 vm.Context instances inside reusable worker threads.
• Speed: Fast suite reuse with fresh global scopes per file.

Main Vitest Runner (Orchestrator)
        |
        +---> Worker 1 (tinypool) ---> Runs User.test.ts
        |
        +---> Worker 2 (tinypool) ---> Runs Order.test.ts
        |
        +---> Worker 3 (tinypool) ---> Runs Payment.test.ts

Communication between the main process and worker threads happens over IPC (Inter-Process Communication) or MessageChannel ports, transferring test results, assertion counts, and console output back to the terminal reporter.