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 ```typescript 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.