microsoft/playwright · error · Error

"not" matcher requires expected result

Error message

"not" matcher requires expected result

What it means

Thrown by the screenshot expectation engine (used by expect(page).toHaveScreenshot()) when the matcher is negated (.not) but no expected/baseline image was supplied. Negation requires an existing reference to compare against; without one, Playwright cannot decide what 'does not match' means, so it refuses rather than auto-creating a baseline under a negation.

Source

Thrown at packages/playwright-core/src/server/page.ts:733

    const locator = options.locator;
    const rafrafScreenshot = locator ? async (progress: Progress, timeout: number) => {
      return await locator.frame.rafrafTimeoutScreenshotElementWithProgress(progress, locator.selector, timeout, options || {});
    } : async (progress: Progress, timeout: number) => {
      await this.performActionPreChecks(progress);
      await this.mainFrame().rafrafTimeout(progress, timeout);
      return await this.screenshotter.screenshotPage(progress, options || {});
    };

    let intermediateResult: {
      actual?: Buffer,
      previous?: Buffer,
      errorMessage: string,
      diff?: Buffer,
    } | undefined;

    try {
      if (!options.expected && options.isNot)
        throw new Error('"not" matcher requires expected result');
      const format = validateScreenshotOptions(options || {});
      const comparator = getComparator(`image/${format}`);
      const areEqualScreenshots = (actual: Buffer | undefined, expected: Buffer | undefined, previous: Buffer | undefined) => {
        const comparatorResult = actual && expected ? comparator(actual, expected, options) : undefined;
        if (comparatorResult !== undefined && !!comparatorResult === !!options.isNot)
          return true;
        if (comparatorResult)
          intermediateResult = { errorMessage: comparatorResult.errorMessage, diff: comparatorResult.diff, actual, previous };
        return false;
      };
      let actual: Buffer | undefined;
      let previous: Buffer | undefined;
      const pollIntervals = [0, 100, 250, 500];
      if (options.expected)
        progress.log(`  verifying given screenshot expectation`);
      else
        progress.log(`  generating new stable screenshot expectation`);
      let isFirstIteration = true;

View on GitHub (pinned to c8fc3bf8d3)

Solutions

1. Run the assertion without .not once to generate the baseline (expect(page).toHaveScreenshot('name.png')), commit the snapshot, then re-add .not.
2. Verify the snapshot name matches an existing file in the snapshots directory and that snapshots are committed to the repo.
3. If you genuinely want 'no screenshot matches X', supply an explicit expected buffer via the lower-level API rather than relying on auto-baseline under negation.

Example fix

// before
await expect(page).not.toHaveScreenshot('home.png'); // no baseline yet -> throws
// after (generate baseline first)
await expect(page).toHaveScreenshot('home.png'); // run once, commit snapshot
await expect(page).not.toHaveScreenshot('home.png'); // now valid

// Ensure a baseline exists before using .not
import { existsSync } from 'node:fs';
import path from 'node:path';
function hasBaseline(testDir, name) {
  return existsSync(path.join(testDir, '-snapshots', name));
}
// only negate when a baseline file is present
const negate = hasBaseline(__dirname, 'home-chromium.png') ? '.not' : '';

try {
  await expect(page).not.toHaveScreenshot('home.png');
} catch (e) {
  if (/"not" matcher requires expected result/.test(e.message))
    throw new Error('No baseline for negated screenshot; run toHaveScreenshot once to generate it');
  throw e;
}

When it happens

Trigger: Using expect(page).not.toHaveScreenshot() before any baseline has been generated; referencing a snapshot name whose expected file was deleted or never committed; running .not.toHaveScreenshot on a fresh project with an empty snapshot directory.

Common situations: First test run before baselines exist; CI on a clean checkout where snapshot artifacts are gitignored; a typo in the snapshot name causing Playwright to look for a non-existent expectation.

Related errors

• The page has closed
• Invalid input image
• path: unsupported mime type "${mimeType}"
• Not implemented
• Cannot take screenshot larger than 32767 pixels on any dimen

AI-assisted analysis of microsoft/playwright@c8fc3bf8d3 (2026-08-12). Data as JSON: /api/errors/711043cb8d5ef459. Report an issue: GitHub.