Parallel and Sequential Test Files

Most test files are independent and run faster in parallel. The exception is the handful that share an exclusive resource, like a fixed port, a writable temp directory, or a database without per-test isolation. Those files flake when other tests run concurrently with them.

Disabling parallelism globally would slow down every test in the suite. Splitting the suite into two projects, one parallel and one sequential, lets only the affected files pay the cost.

Pattern

vitest.config.ts

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'Parallel',
          exclude: ['**.sequential.test.ts'],
        },
      },
      {
        test: {
          name: 'Sequential',
          include: ['**.sequential.test.ts'],
          fileParallelism: false,
        },
      },
    ],
  },
})

fileParallelism: false at the project level keeps the rest of your suite running concurrently while the matched files run one at a time. It's a shorthand for maxWorkers: 1; the two settings are equivalent.

Run sequential after parallel

By default, projects run in parallel with each other, so the sequential project's first file may overlap with parallel files that still hold the same resource. Use sequence.groupOrder 3.2.0+ to force the parallel batch to finish first:

vitest.config.ts

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'Parallel',
          exclude: ['**.sequential.test.ts'],
          sequence: { groupOrder: 0 },
        },
      },
      {
        test: {
          name: 'Sequential',
          include: ['**.sequential.test.ts'],
          fileParallelism: false,
          sequence: { groupOrder: 1 },
        },
      },
    ],
  },
})

The parallel batch finishes, then the sequential batch starts. Total wall clock stays close to the parallel time plus sum of the sequential test run time.

File scope vs. test scope

There are two different "parallel" knobs in Vitest. Don't confuse them:

Scope	Knob	Controls
Across files	`fileParallelism`	Whether two test files run in parallel workers
Within a file	`describe.concurrent` / `test.concurrent`	Whether tests inside one file run concurrently

fileParallelism: false doesn't make tests inside a file concurrent; tests inside a file are sequential by default. And concurrent on a describe or test doesn't affect how files are scheduled.

Introduction

Learn

Browser Mode

Authoring

Mocking

Workflow

Quality & Debugging

Performance

Recipes

Advanced

Migration

Parallel and Sequential Test Files

Pattern

Run sequential after parallel

File scope vs. test scope

See also