vitest-dev/vitest · error · Error

Snapshot cannot be used outside of test

Error message

Snapshot cannot be used outside of test

What it means

Thrown by SnapshotClient.match() when the filepath option is falsy. Vitest derives filepath from the running test's task context, so a missing filepath means the snapshot assertion executed without an active test (e.g. at module top level, inside a worker that isn't a test, or via a hand-rolled SnapshotClient with no setup() call). The library refuses to write or compare a snapshot because it has nowhere to persist it and no test lifecycle to attach it to.

Source

Thrown at packages/snapshot/src/client.ts:134

  match(options: AssertOptions): MatchResult {
    const {
      filepath,
      name,
      testId = name,
      message,
      isInline = false,
      properties,
      inlineSnapshot,
      error,
      errorMessage,
      rawSnapshot,
      assertionName,
    } = options
    let { received } = options

    if (!filepath) {
      throw new Error('Snapshot cannot be used outside of test')
    }

    const snapshotState = this.getSnapshotState(filepath)
    const testName = [name, ...(message ? [message] : [])].join(' > ')

    // Probe first so we can mark as checked even on early return
    const expectedSnapshot = snapshotState.probeExpectedSnapshot({
      testName,
      testId,
      isInline,
      inlineSnapshot,
    })

    if (typeof properties === 'object') {
      if (typeof received !== 'object' || !received) {
        expectedSnapshot.markAsChecked()
        throw new Error(
          'Received value must be an object when the matcher has properties',

View on GitHub (pinned to d568f8ce37)

Solutions

1. Move the expect(...).toMatchSnapshot() call inside an it() or test() callback so Vitest can bind the current test's filepath.
2. If you are using SnapshotClient directly, call await client.setup(filepath, options) and pass a non-empty filepath into match().
3. Check that the file is being collected as a test file (matches test.include) and is not loaded as a regular module.
4. Ensure the assertion is not running in a hook (beforeAll/afterAll) or at top level where there is no current task.

Example fix

// before
import { expect } from 'vitest'
expect({ a: 1 }).toMatchInlineSnapshot()

// after
import { expect, test } from 'vitest'
test('snapshot', () => {
  expect({ a: 1 }).toMatchInlineSnapshot()
})

import { getCurrentTest } from '@vitest/runner'

if (getCurrentTest()) {
  expect(value).toMatchSnapshot()
} else {
  // not in a test — skip or assert in a different way
}

import type { Task } from 'vitest'
function insideTest(t: unknown): t is Task {
  return typeof t === 'object' && t !== null && 'id' in t && 'name' in t
}

When it happens

Trigger: Calling expect(x).toMatchSnapshot() (or toMatchInlineSnapshot / toThrowErrorMatchingSnapshot) outside of an it/test/it.each callback; constructing a SnapshotClient directly and calling client.match({ filepath: '', ... }); running an assertion in a setup file, afterAll, or a bare script that Vitest does not register as a test module.

Common situations: Hoisting expect().toMatchSnapshot() to module scope by mistake; calling snapshot assertions inside describe body instead of inside it(); using the snapshot client in a non-Vitest runner without calling client.setup(filepath, options) first; refactoring that moved an assertion out of a test function.

Related errors

• '${getAssertionName(obj)}' cannot be used without test conte
• Cannot take a screenshot without a test path
• stopChunkTrace cannot be called outside of the test file.
• This command can only be called inside a test file.
• Cannot upload files outside of a test

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/108672be86643374.json. Report an issue: GitHub.