Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Visual regression testing detects unintended changes to the appearance of your UI by comparing screenshots against approved baselines. It catches CSS regressions, layout shifts, font changes, color modifications, and other visual issues that functional tests miss because they don't assert on how things look.
When Visual Testing Matters
Scenario
Why
Design systems / component libraries
Every component must match the design spec exactly
CSS refactors
Changing shared styles can break distant pages
Dependency upgrades
Font, icon, or framework updates can shift layouts
Theme / dark mode
Multiple visual variants to verify
Cross-browser support
Same code renders differently across browsers
Responsive breakpoints
Layout changes at mobile, tablet, desktop widths
Cross-Platform Tools
Tool
Integration
Approach
Pricing
Chromatic
Storybook
Cloud-hosted visual snapshots of every story
Free tier + paid
Percy (BrowserStack)
Any framework
Cloud-hosted cross-browser visual diffs
Paid
BackstopJS
Standalone
Local headless CSS regression with reference images
Chromatic is a cloud-based visual testing service built by the Storybook maintainers. It captures a snapshot of every Storybook story on every commit and detects visual changes with a review/approve workflow.
# Run locally (requires project token from chromatic.com)
npx chromatic --project-token=<your-project-token>
# Run with TurboSnap (only test stories affected by code changes)
npx chromatic --project-token=<your-project-token> --only-changed
# Accept all changes (auto-approve — use for initial baseline)
npx chromatic --project-token=<your-project-token> --auto-accept-changes
CI Integration (GitHub Actions)
# .github/workflows/chromatic.ymlname:Chromaticon:pushjobs:chromatic:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4with:fetch-depth:0# Required for TurboSnap-uses:actions/setup-node@v4with:node-version:20-run:npmci-uses:chromaui/action@latestwith:projectToken:${{secrets.CHROMATIC_PROJECT_TOKEN}}onlyChanged:true# TurboSnapexitZeroOnChanges:true# Don't fail CI — review in Chromatic UIexitOnceUploaded:true# Don't wait for cloud processing
Percy captures snapshots at multiple browser/viewport combinations in the cloud. It integrates with Playwright, Cypress, Selenium, Storybook, and static sites.
BackstopJS is a free, open-source visual regression tool that runs headless Chrome/Firefox locally. It compares test screenshots against reference images and generates an HTML diff report.
# Install BackstopJS
npm install -g backstopjs
# 1. Create initial reference screenshots (baseline)
backstop reference
# 2. Run tests — compare current state against references
backstop test# 3. Review the HTML diff report (opens in browser)# reports show: reference / test / diff side by side# 4. Approve changes — update references to match current state
backstop approve
# Typical workflow:# reference → develop → test → review → approve (if intended) → commit
CI Integration
# .github/workflows/backstop.ymljobs:visual-test:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-uses:actions/setup-node@v4with:node-version:20-run:npmci-run:npmstart&# Start the app-run:npxwait-onhttp://localhost:3000-run:npxbackstopjstest--configbackstop.json-uses:actions/upload-artifact@v4if:always()with:name:backstop-reportpath:tests/visual/backstop_data/html_report/
Playwright Screenshot Assertions
Overview
Playwright has built-in visual comparison via toHaveScreenshot() and toMatchSnapshot(). No external service required — baselines are stored in the repository.
// playwright.config.jsimport { defineConfig } from"@playwright/test";
exportdefaultdefineConfig({
testDir: "tests/visual",
expect: {
toHaveScreenshot: {
// Default comparison optionsmaxDiffPixels: 50,
maxDiffPixelRatio: 0.01,
threshold: 0.2, // Per-pixel color threshold (0-1)animations: "disabled", // Disable CSS animations for stability
},
},
// Run visual tests on a single browser for consistencyprojects: [
{
name: "visual-chromium",
use: {
browserName: "chromium",
viewport: { width: 1280, height: 720 },
},
},
],
});
Updating Baselines
# Run tests — first run creates baselines automatically
npx playwright test tests/visual/
# Update baselines after intentional visual changes
npx playwright test tests/visual/ --update-snapshots
# Update specific test baseline
npx playwright test tests/visual/pages.spec.js -g "homepage" --update-snapshots
Applitools Eyes
Overview
Applitools Eyes uses AI-powered visual comparison with multiple match levels: Strict (pixel-level), Layout (structure only), Content (text/images), and Dynamic (ignores dynamic regions). This significantly reduces false positives compared to pixel-based tools.
