Visual Testing

Visual testing

Catch unintended visual change. Rendered UI is deterministic enough that a pixel which moved without an intended cause is worth seeing — a card that lost its shadow, a table that overflows on tablet, a button that drifted but still works. This skill screenshots each screen and diffs it against a baseline captured when the UI was last correct.

Two halves, kept separate on purpose:

• Capture is agent-driven. You open the thing under test in whatever browser or device tool you already have and save a PNG. No headless browser is bundled or installed — capture rides on the tooling that already exists (a connected browser, a Playwright/Appium session, a running app's automation).
• Diff is browser-free. scripts/visual-diff.mjs shells out to reg-cli (resolved local-first, else npx --yes reg-cli@latest, so nothing is added to package.json) to compare, manage baselines, and write a report.

Workflow

1. Render the thing under test.
   • A generated static page → build it, then open the HTML from disk (file://); the pages are self-contained, no server needed.
   • A running app → drive it to the screen/state with the automation you already use (Playwright for web, the device tooling for mobile). This is the same navigation a functional check performs — the visual diff is an extra assertion, not a separate run.
2. Capture each screen into a current/ directory, one PNG per variant, named by the scheme below. See references/capturing.md for driving each source and controlling the noise that makes diffs flaky.
3. Diff against the baseline:

   node scripts/visual-diff.mjs --current <current/> --baseline <baselines/> --diff <out/>
   

   Exit 0 = no change; exit 1 = something changed (report at <out/>/report.html).
4. Review the report. An intended change (a redesign, a shipped restyle) → promote it: node scripts/visual-diff.mjs --current <current/> --baseline <baselines/> --diff <out/> --update then commit the updated baselines. An unintended change → a finding: fix the cause (or file the defect with the diff image); do not update the baseline.

A green diff is not a passing test. It proves the screen is unchanged since the baseline — nothing about whether that baseline was ever correct or whether the feature works. Use it to hold a reviewed UI steady, alongside the checks that judge correctness, never instead of them.

Naming (this is what pairs a shot with its baseline)

reg-cli matches current/<name>.png to baselines/<name>.png by filename, so names must be stable and describe exactly one variant. Pick a scheme that fits what you're testing and keep it lowercase and stable; examples:

Renaming a file breaks its baseline pairing — reg-cli then reports one deleted + one new, which is the signal to re-approve, not a bug.

Keep the baseline set honest

Screens × states × sizes/styles is a combinatorial trap. Default coverage: the screens actually touched, in their default state, at the size/device set you target, in one representative variant. Add more only where a real regression risk lives. Every variant is a baseline someone re-approves on every intended change — a giant set nobody re-approves is worse than a focused one people actually look at.

Files