pw-visual-regression

name	pw-visual-regression
description	Sets up Playwright visual/screenshot regression testing. Use when an SDET says "add visual regression", "snapshot this component", "set up toHaveScreenshot", "mask the dynamic parts of this page", or "manage baselines". Produces snapshot tests with masking, thresholds, and a baseline strategy — a draft the engineer runs to generate and review the first baselines.
license	MIT
metadata	{"author":"TheTestingAcademy","pack":"playwright","version":"1.0.0"}

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.