Vitest Parallel Execution: Deterministic Test Ordering Across OS Environments

Vitest does not provide a native mechanism to enforce a deterministic execution sequence while maintaining parallel worker distribution. Because Vitest uses a worker pool that consumes tests as they become available, the execution order is inherently tied to file system discovery speed and thread scheduling, which vary significantly between operating systems.

To guarantee a consistent order across heterogeneous environments while still utilizing parallel workers, you must move away from relying on the default discovery order and implement explicit sorting strategies.

Why Ordering Varies

The inconsistency stems from how different OS file systems (NTFS on Windows, APFS on macOS, and ext4 on Linux) handle directory traversal. When Vitest scans for test files, the order in which files are returned is not guaranteed to be alphabetical. In a parallel environment, the first worker to become idle will claim the first available file, leading to the non-deterministic behavior you observed.

Strategies for Deterministic Execution

If your CI/CD pipeline requires a specific sequence for debugging race conditions or managing implicit dependencies, use the following methods:

• File Prefixing and Stable Sorting: The most reliable way to ensure a consistent sequence is to prefix your test files with numeric indices (e.g., 01-auth.spec.ts, 02-user.spec.ts). While Vitest sorts discovered files alphabetically by default before dispatching to workers, numeric prefixes remain consistent across OS environments.
• The --runInBand Flag: For environments where order is critical (like debugging), run Vitest with the --runInBand flag. This forces all tests to run sequentially in the main thread, eliminating the worker pool's scheduling variability.
• Configuration Options: You can limit the concurrency in your vitest.config.ts to reduce resource contention, though this does not strictly guarantee order unless concurrency is set to 1.

Example Configuration for Sequential Consistency

export default defineConfig({
  test: {
    poolOptions: {
      threads: {
        single // Forces sequential execution to ensure order
    }
    }
  }
})

Are your tests relying on shared global state between files, or are you primarily trying to reproduce a specific failure sequence in CI?