toolkit

Screenshots · Playbook

Visual-regression testing (reference)

viewvee ships a Playwright test project that guards pages against visual change across devices.

Config

playwright.config.ts defines one project per device (iphone-13, ipad-pro-11, laptop, desktop) and a shared spec (tests/visual.spec.ts) that screenshots each URL and asserts toHaveScreenshot(). Diff tolerance is maxDiffPixelRatio: 0.02; animations disabled.

Workflow

# 1. First run / after an intentional UI change — write baselines
VIEWVEE_URLS="https://example.com,https://your.app" npm run test:visual:update

# 2. CI / pre-merge — fail on any visual diff
VIEWVEE_URLS="https://example.com,https://your.app" npm run test:visual
  • VIEWVEE_URLS is a comma-separated list; omit it to default to https://example.com.
  • Baselines are written to tests/__screenshots__/ — commit them. A diff produces an HTML report (playwright-report/) with side-by-side actual/expected/diff.

Notes

  • Bot-protected URLs can’t be baselined headlessly (see the bot-challenge limitation). Either test only reachable URLs, or run behind the WAF-bypass header on zones you own.
  • Tighten tolerance per assertion in tests/visual.spec.ts if 2% is too loose for a given page.
  • To add device coverage, add a project to playwright.config.ts.
  • Unstable page height: some sites render a slightly different full-page height run-to-run (lazy-load timing), which can cause spurious full-page diffs. If a page flaps, add --settle (via a longer wait in the spec) so content fully settles, or scope the assertion to a stable region instead of the whole page.