vitest-dev/vitest · error · Error

Cannot use the `bench` test-context fixture within a…

Error message

Cannot use the `bench` test-context fixture within a regular test run. Benchmarks are inherently flaky, so Vitest runs them in a dedicated project based on the `benchmark.include` pattern (default `**/*.{bench,benchmark}.?(c|m)[jt]s?(x)`). Move this code to a file matched by `benchmark.include`, and make sure `bench` is destructured from the test context (`test('...', async ({ bench }) => { ... })`) — it is not a top-level export of `vitest`. See https://vitest.dev/guide/benchmarking#stability

What it means

The `bench` fixture is only available on the test context inside projects whose `benchmark.enabled` config is true (i.e. files matched by `benchmark.include`). Vitest isolates benchmarks into a dedicated project because they are inherently flaky. This error fires when `bench` is destructured and used inside a regular (non-benchmark) test run — `config.benchmark.enabled` is false.

Solutions

Move the benchmark code into a file matching `benchmark.include` (e.g. `*.bench.ts`).
Run with `vitest bench` (or `vitest --project <bench-project>`) so `benchmark.enabled` is true.
Ensure the bench project is configured: `benchmark: { include: ['**/*.bench.ts'] }` and the file is matched.
Access `bench` only via the test context: `test('...', async ({ bench }) => { ... })` — never as a top-level import.

Example fix

// before - src/sort.test.ts (run via `vitest`)
test('sort perf', async ({ bench }) => {
  bench('sort', sortFn)
})

// after - src/sort.bench.ts (run via `vitest bench`)
test('sort perf', async ({ bench }) => {
  bench('sort', sortFn)
})

Defensive patterns

Strategy: validation

Validate before calling

if (!config.benchmark.enabled) throw new Error('run via `vitest bench`; this file is not in benchmark.include')

Type guard

null

Try / catch

null

Prevention

Name benchmark files `*.bench.ts` to match the default `benchmark.include`.
Run benchmarks with `vitest bench`, not `vitest`.
Never `import { bench } from 'vitest'` — it is a context fixture only.
Configure a dedicated bench project in the workspace config.

When it happens

Trigger: Destructuring `{ bench }` from the test context in a file NOT matched by `benchmark.include` (default `**/*.{bench,benchmark}.?(c|m)[jt]s?(x)`); running `vitest` (not `vitest bench`) on a file that uses the `bench` fixture; importing `bench` as a top-level export from `vitest` (it is not one). The guard is `validateBenchmarkProject` at benchmark.ts:597-605.

Common situations: Putting benchmark code in a `*.test.ts` file; running the default `vitest` command instead of `vitest bench`; a project config that overrides `include` to also match bench files but does not set `benchmark.enabled`; trying `import { bench } from 'vitest'`.

Related errors

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/e253a42df00e7cbf. Report an issue: GitHub.

Appendix: source

Thrown at packages/vitest/src/runtime/benchmark.ts:599

  // Strip vitest-specific fields only when present so we don't allocate a new
  // object — preserving referential identity matters: users inspect
  // `registration.fnOpts` and the provider sees the same object the caller
  // passed in.
  if (a.writeResult === undefined && a.perProject === undefined) {
    return { fn: b, fnOpts: a as BenchOptions, writeResult: undefined, perProject: false }
  }
  const { writeResult, perProject, ...fnOpts } = a
  return {
    fn: b,
    fnOpts: Object.keys(fnOpts).length > 0 ? fnOpts as BenchOptions : undefined,
    writeResult,
    perProject: perProject ?? false,
  }
}

function validateBenchmarkProject(config: SerializedConfig) {
  if (!config.benchmark.enabled) {
    throw new Error(
      `Cannot use the \`bench\` test-context fixture within a regular test run. `
      + `Benchmarks are inherently flaky, so Vitest runs them in a dedicated project based on the \`benchmark.include\` pattern (default \`**/*.{bench,benchmark}.?(c|m)[jt]s?(x)\`). `
      + `Move this code to a file matched by \`benchmark.include\`, and make sure \`bench\` is destructured from the test context (\`test('...', async ({ bench }) => { ... })\`) — it is not a top-level export of \`vitest\`. `
      + `See https://vitest.dev/guide/benchmarking#stability`,
    )
  }
}

View on GitHub (pinned to 1fa9837ec2)