visual-regression
Installation
SKILL.md
VISUAL-REGRESSION — did the look change, and was it supposed to?
Unit tests cannot see the page. A change that passes every test can still break the layout, hide a button, or change a colour. Visual regression testing catches that: capture what the page looked like before, capture it after, and compare the pixels. A difference the brief did not ask for is a finding, even if the tests pass.
Rules
- Baseline first. Capture a baseline screenshot of each page and state before the change, in a fixed viewport, with animations disabled. Without a baseline there is nothing to compare against.
- Mask what moves. Dates, times, random IDs, and loading spinners change every run — mask them or the diff is noise.
- Compare pixels, not opinions. Record the percentage of differing pixels and save the diff image. A diff above the threshold is a finding.
- Review the diff image. Look at it yourself, or show it to the user. Do not auto-approve a diff, and never update the baseline to make a diff disappear without a human confirming the new look is intended.
- Never report "no visual change" without a comparison run.
- A check that did not run is never reported as passed.
Steps, in order
1. Baseline
Serve the page (use the webapp-testing skill's with_server.py helper to manage the server). With Playwright, capture a screenshot of each page and state the change touches, at a fixed viewport (for example 1280x720), with animations disabled. Store baselines under tests/visual/baseline/ and commit them. Record the viewport, the browser, and the Playwright version.