Visual Regression Testing

Command

/visual-regression

Description

Configures and executes visual regression testing for your frontend application. Takes screenshots of specified pages or components, compares them against approved baselines, and generates a visual diff report showing exactly what changed. Supports Playwright, Puppeteer, and Cypress screenshot backends.

Behavior

1. Setup (first run):

   • Detect existing test framework (Playwright, Cypress, Puppeteer)
   • Create visual-tests/ directory with baseline and diff folders
   • Generate config file with viewport sizes and test targets
   • Install required dependencies (pixelmatch, pngjs)

2. Capture -- Take screenshots of all configured pages/components

3. Compare -- Pixel-diff each screenshot against its baseline

4. Report -- Generate an HTML report with side-by-side comparisons

5. Update -- Approve new baselines when changes are intentional

Output Format

Directory Structure

visual-tests/
├── baselines/          # Approved reference screenshots
│   ├── homepage-desktop.png
│   ├── homepage-mobile.png
│   └── login-form.png
├── current/            # Latest test screenshots
├── diffs/              # Highlighted differences
├── report.html         # Visual comparison report
└── config.json         # Test configuration

Configuration (visual-tests/config.json)

Copy
{
  "baseUrl": "http://localhost:3000",
  "threshold": 0.1,
  "viewports": [
    { "name": "desktop", "width": 1280, "height": 720 },
    { "name": "tablet", "width": 768, "height": 1024 },
    { "name": "mobile", "width": 375, "height": 812 }
  ],
  "pages": [
    { "name": "homepage", "path": "/", "waitFor": ".hero-section" },
    { "name": "login", "path": "/login", "waitFor": "form" },
    { "name": "dashboard", "path": "/dashboard", "auth": true }
  ],
  "ignore": [
    { "selector": ".timestamp", "reason": "Dynamic content" },
    { "selector": ".avatar", "reason": "User-specific" }
  ]
}

Test Report Summary

Visual Regression Results:
  ✓ homepage-desktop      (0.00% diff)
  ✓ homepage-mobile        (0.02% diff)
  ✗ login-form-desktop     (3.47% diff) → diffs/login-form-desktop.png
  ✓ dashboard-desktop      (0.00% diff)

1 of 4 tests failed. See report.html for details.

Examples

/visual-regression --setup                  # First-time configuration
/visual-regression                          # Run all visual tests
/visual-regression --update-baselines       # Approve current as new baseline
/visual-regression --page homepage          # Test specific page only
/visual-regression --viewport mobile        # Test specific viewport only
/visual-regression --threshold 0.5          # Allow up to 0.5% pixel difference