Visual Regression Testing Protocol
Use this skill when implementing automated UI regression tests, visual snapshot comparisons, or catching unintended CSS and WebGL layout shifts.
Methodology & Tooling
1. Snapshot Isolation & Flakiness Prevention
- Disable Animations & Carets:
- Inject CSS to disable transitions, animations, and blinking carets before taking snapshots:
*, *::before, *::after { transition: none !important; animation: none !important; caret-color: transparent !important; }
- Inject CSS to disable transitions, animations, and blinking carets before taking snapshots:
- Consistent Viewports: Always lock fixed viewport dimensions (e.g.
1280x720desktop,375x812mobile) and explicit device scale factors (deviceScaleFactor: 2for Retina). - Web Font Readiness: Never capture screenshots until
document.fonts.readyresolves, preventing font-swap layout shifts.
2. Difference Thresholds & Anti-Aliasing
- Render engines on different OS platforms (Linux CI vs macOS dev) produce minor anti-aliasing variations.
- Use threshold-aware diffing algorithms (such as
pixelmatchor Playwright's built-intoHaveScreenshot):- Set
maxDiffPixelRatio: 0.01(allows up to 1% difference). - Set
threshold: 0.2(per-pixel color distance sensitivity). - Mask dynamic elements (timestamps, random user avatars, live video feeds) using test locators.
- Set
3. CI Baseline Management
- Store reference snapshots in Git LFS or object storage.
- When intentional UI redesigns occur, update baselines via a dedicated
--update-snapshotsCI run with peer review approval.