{"record":{"id":"7956e77a5d9c29c9","repo":"vitest-dev/vitest","slug":"cannot-compare-screenshots-without-a-test-path","errorCode":null,"errorMessage":"Cannot compare screenshots without a test path","messagePattern":"Cannot compare screenshots without a test path","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/browser/src/node/commands/screenshotMatcher/index.ts","lineNumber":84,"sourceCode":"/**\n * Browser command that compares a screenshot against a stored reference.\n *\n * The comparison workflow is organized as follows:\n *\n * 1. Load existing reference (if any)\n * 2. Capture a stable screenshot (retrying until the page stops changing)\n * 3. Determine the outcome based on capture results and update settings\n * 4. Write any necessary files (new references, diffs)\n * 5. Return result for the test runner\n */\nexport const screenshotMatcher: BrowserCommand<ScreenshotMatcherArguments> = async (\n  context,\n  name,\n  testName,\n  options,\n): ScreenshotMatcherOutput => {\n  if (!context.testPath) {\n    throw new Error('Cannot compare screenshots without a test path')\n  }\n\n  const { element, target } = options\n  const {\n    codec,\n    comparator,\n    paths,\n    resolvedOptions: { comparatorName, comparatorOptions, screenshotOptions, timeout },\n  } = resolveOptions({ context, name, testName, options })\n\n  const screenshotName = `${Date.now()}-${basename(paths.reference)}`\n  const screenshotCaptureOptions = {\n    context,\n    element,\n    name: screenshotName,\n    screenshotOptions,\n    target,\n  } satisfies Parameters<typeof takeScreenshotBuffer>[0]","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser/src/node/commands/screenshotMatcher/index.ts#L66-L102","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: command triggered outside a test (context.testPath is undefined)\ncommands.triggerCommand('__vitest_screenshotMatcher', [name, testName, opts])\n\n// after\ntest('visual', () => {\n  expect(page).toMatchScreenshot('home')\n})","handlingStrategy":"validation","validationCode":"// ensure a test path is available before triggering the command\nif (!context.testPath) {\n  throw new Error('Screenshot matcher requires a test path; invoke it inside a test()')\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["screenshot","browser-command","test-context","browser"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}