Playwright "A snapshot doesn't match its reference" in CI

By Kaveh Alemi·Latchkey

Playwright captured a fresh screenshot, compared it pixel by pixel against the committed reference, and the number of differing pixels exceeded the threshold. The most common CI cause is that the baseline was generated on a different OS or font stack than the runner.

What this error means

A toHaveScreenshot() or toMatchSnapshot() assertion fails with "Error: A snapshot doesn't match its reference." Playwright writes -actual.png, -expected.png, and -diff.png into the test-results output for inspection.

  Error: A snapshot doesn't match its reference.

    Expected: tests/example.spec.ts-snapshots/hero-chromium-linux.png
    Received: test-results/example-hero/hero-actual.png
        Diff: test-results/example-hero/hero-diff.png

    12483 pixels (ratio 0.02 of all image pixels) are different.

Common causes

Baseline generated on a different OS than the runner

Reference images encode the platform in their name (for example -chromium-linux.png). If a developer committed baselines from macOS but CI runs on Linux, font hinting and anti-aliasing differ and the diff exceeds threshold.

A genuine visual change landed without updating the baseline

The UI actually changed (spacing, color, copy) and the committed reference is now stale. The diff image shows the real regression.

How to fix it

Generate baselines in the same container as CI

1. Open the -diff.png artifact to confirm whether the change is real or a rendering artifact.
2. If it is only rendering differences, regenerate baselines inside the official Playwright Docker image so they match the runner exactly.
3. Commit the Linux baselines and re-run.

docker run --rm --network host -v $(pwd):/work -w /work \
  mcr.microsoft.com/playwright:v1.44.0-jammy \
  npx playwright test --update-snapshots

Update the baseline when the change is intentional

If the diff shows a real, wanted UI change, refresh the reference with --update-snapshots and commit the new PNG.

npx playwright test --update-snapshots

How to prevent it

• Generate and update screenshot baselines inside the same Docker image CI uses.
• Commit the per-platform baseline that matches your runner OS.
• Review the -diff.png artifact before assuming a failure is flaky.

Frequently asked questions

Related guides

References

• GitHub Actions documentation