Pw Visual Regression

PW Visual Regression

You set up snapshot tests whose first baselines the engineer must generate and eyeball — never trust an auto-approved baseline. You make snapshots deterministic.

When to use

• A page or component needs pixel/visual regression coverage.
• Flaky snapshot diffs need masking or threshold tuning.
• Someone says "add visual regression", "manage/update baselines".

Workflow

1. Pick the smallest stable target — prefer a component locator over a full page; less surface means fewer false diffs.
2. Neutralize non-determinism before snapping: mask dynamic regions (dates, avatars, ads), disable animations (animations: 'disabled'), freeze data, and pin viewport + a consistent font/rendering environment (ideally Docker in CI).
3. Configure tolerances deliberately — maxDiffPixelRatio / threshold in config, not sprinkled ad hoc. Tight enough to catch real regressions.
4. Establish baselines via --update-snapshots, then review each PNG by eye before committing — a wrong baseline locks in the bug.
5. Document the update flow so baselines are refreshed intentionally, per platform.

Output shape

import { test, expect } from '@playwright/test';

test('dashboard card matches baseline', async ({ page }) => {
  await page.goto('/dashboard');
  const card = page.getByTestId('summary-card');
  await expect(card).toBeVisible();                       // web-first: wait for render
  await expect(card).toHaveScreenshot('summary-card.png', {
    animations: 'disabled',
    mask: [page.getByTestId('last-updated')],             // hide volatile timestamp
    maxDiffPixelRatio: 0.01,
  });
});

# generate/refresh baselines, then review the PNGs before committing
npx playwright test --update-snapshots

Guardrails

• Baselines are generated then human-reviewed — never auto-approve; a bad baseline turns a bug green forever. Never assume a locator/testid exists.
• Mask every dynamic region and disable animations, or diffs will be flaky.
• Pin viewport, OS, and fonts; snapshots taken on different platforms won't match — generate per-project baselines in the CI environment, not just locally.
• No waitForTimeout before snapping; wait on a web-first assertion instead.