Detect visual changes in UI components using screenshot comparison.
ReadWriteEditGrepGlobBash(test:visual-*)
Visual Regression Tester
Overview
Detect unintended visual changes in UI components by capturing screenshots and comparing them pixel-by-pixel against approved baselines. Supports Playwright visual comparisons, Percy, Chromatic, BackstopJS, and reg-suit.
Prerequisites
- Browser automation tool installed (Playwright, Puppeteer, or Cypress)
- Visual regression library configured (Playwright
toHaveScreenshot, Percy, Chromatic, or BackstopJS)
- Baseline screenshots committed to version control or stored in a cloud service
- Storybook or component playground running for isolated component captures (optional)
- Consistent rendering environment (Docker or CI with fixed OS/fonts/GPU settings)
Instructions
- Identify all UI components and pages requiring visual coverage using Glob to scan component directories and route definitions.
- Create a visual test file for each component or page:
- Navigate to the component URL or Storybook story.
- Wait for all network requests, animations, and lazy-loaded images to complete.
- Set a consistent viewport size (e.g., 1280x720 for desktop, 375x812 for mobile).
- Capture screenshots with deterministic settings:
- Disable animations and transitions (
* { animation: none !important; transition: none !important; }).
- Mask dynamic content (timestamps, random avatars, ads) with CSS overlays.
- Use
fullPage: true for scrollable pages.
- Compare captured screenshots against baselines:
- Configure pixel difference threshold (recommended: 0.1% for component tests, 0.5% for full-page).
- Generate diff images highlighting changed regions.
- Flag tests as failed when differences exceed the threshold.
- For responsive testing, capture at multiple breakpoints:
- Mobile: 375px width
- Tablet: 768px width
- Desktop: 1280px width
- Wide: 1920px width
- Review diff images for each failure and classify as:
- Intentional change: Update the baseline with
--update-snapshots.
- Regression: File a bug with the diff image attached.
- Integrate into CI so visual tests run on every pull request with diff images uploaded as artifacts.
Output
- Screenshot baseline images stored in
__screenshots__/ or equivalent directory
- Diff images highlighting pixel-level changes between baseline and current
- Visual regression test report with pass/fail status per component
- CI artifacts containing all captured, baseline, and diff images
- Responsive coverage matrix showing results across breakpoints
Error Handling
E
Ready to use visual-regression-tester?
|