Set up stable screenshot visual diffing for pixel-level regression comparisons in Playwright

domain: playwright.dev · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Use Playwright's built-in `expect(page).toHaveScreenshot('name.png')` assertion — on first run it creates the baseline; on subsequent runs it compares and fails if the diff exceeds the threshold.
  2. Commit baseline screenshots to source control alongside test files so reviewers can inspect visual changes and CI uses the same baselines as local development.
  3. Configure a pixel-difference threshold and/or maximum diff pixel count in `playwright.config.ts` under `expect.toHaveScreenshot` to tolerate sub-pixel anti-aliasing differences: `{ threshold: 0.2, maxDiffPixelRatio: 0.01 }`.
  4. Mask dynamic regions (timestamps, avatars, ads) with `mask: [page.getByTestId('timestamp')]` option on `toHaveScreenshot` to exclude them from comparison.
  5. Generate and update baselines in CI using `npx playwright test --update-snapshots` when an intentional UI change is landed, then commit the new baseline images.

Known gotchas

Related routes

Choose between pixel-diff screenshot comparison and DOM/structural snapshot testing for catching visual regressions
playwright.dev · 5 steps · unrated
integrate percy visual snapshots into a playwright test suite using percy playwright
github.com/percy/percy-playwright · 5 steps · unrated
Use Playwright ARIA snapshot testing to detect accessibility-tree regressions
playwright.dev · 5 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans