What causes "Cannot compare screenshots without a test path" in vitest-dev/vitest?

Invoke `toMatchScreenshot` only from inside a `test()`/`it()` in the browser environment, so Vitest supplies a fully-populated command context.

vitest-dev/vitest · error · Error

Cannot compare screenshots without a test path

Error message

Cannot compare screenshots without a test path

What it means

Thrown by the server-side `screenshotMatcher` browser command when `context.testPath` is falsy. The command uses the test file's path to locate the screenshot reference directory (where baseline/diff images are written); without a test path it cannot place output files, so it refuses to run. `context.testPath` is provided by Vitest's `BrowserCommandContext` when the command runs inside a real test.

Solutions

Invoke `toMatchScreenshot` only from inside a `test()`/`it()` in the browser environment, so Vitest supplies a fully-populated command context.
If triggering the command directly, construct a context whose `testPath` is set to the test file's absolute path.
Confirm the Vitest version is recent; test-path propagation bugs are typically fixed upstream.

Example fix

// before: command triggered outside a test (context.testPath is undefined)
commands.triggerCommand('__vitest_screenshotMatcher', [name, testName, opts])

// after
test('visual', () => {
  expect(page).toMatchScreenshot('home')
})

Defensive patterns

Strategy: validation

Validate before calling

// ensure a test path is available before triggering the command
if (!context.testPath) {
  throw new Error('Screenshot matcher requires a test path; invoke it inside a test()')
}

Prevention

Invoke `toMatchScreenshot` only from within `test()`/`it()` so Vitest populates the command context.
When triggering the command directly, construct a context with a valid `testPath`.
Keep Vitest up to date to benefit from test-path propagation fixes.

When it happens

Trigger: Invoking the `__vitest_screenshotMatcher` browser command outside a test (no `BrowserCommandContext.testPath`); a custom runner that triggers the command with an incomplete context; running the matcher from a script that bypasses the test runner.

Common situations: Manually calling the browser command for debugging; a custom integration that constructs the command context without `testPath`; an upstream bug where the test path is not propagated to the browser command context.

Related errors

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

Appendix: source

Thrown at packages/browser/src/node/commands/screenshotMatcher/index.ts:84

/**
 * Browser command that compares a screenshot against a stored reference.
 *
 * The comparison workflow is organized as follows:
 *
 * 1. Load existing reference (if any)
 * 2. Capture a stable screenshot (retrying until the page stops changing)
 * 3. Determine the outcome based on capture results and update settings
 * 4. Write any necessary files (new references, diffs)
 * 5. Return result for the test runner
 */
export const screenshotMatcher: BrowserCommand<ScreenshotMatcherArguments> = async (
  context,
  name,
  testName,
  options,
): ScreenshotMatcherOutput => {
  if (!context.testPath) {
    throw new Error('Cannot compare screenshots without a test path')
  }

  const { element, target } = options
  const {
    codec,
    comparator,
    paths,
    resolvedOptions: { comparatorName, comparatorOptions, screenshotOptions, timeout },
  } = resolveOptions({ context, name, testName, options })

  const screenshotName = `${Date.now()}-${basename(paths.reference)}`
  const screenshotCaptureOptions = {
    context,
    element,
    name: screenshotName,
    screenshotOptions,
    target,
  } satisfies Parameters<typeof takeScreenshotBuffer>[0]

View on GitHub (pinned to 1fa9837ec2)