Visual Regression Testing
Catch unintended visual changes with pixel-level screenshot comparisons. Manage baselines, review diffs, and accept or reject changes.
Visual Regression Testing
Visual regression testing automatically detects unintended visual changes in your application by comparing screenshots between test runs at the pixel level.
How It Works
On the first run with visual regression enabled, AegisRunner captures a screenshot at each test step. These screenshots become your baselines — the reference for how your app should look.
On every subsequent run, new screenshots are compared against baselines using pixelmatch — a pixel-level comparison algorithm. Any differences are highlighted in a diff image.
When differences are detected, view a three-panel display: baseline (expected), current (actual), and diff (highlighted changes). The diff percentage tells you how much has changed.
If the visual change is intentional (e.g., a redesign), accept it as the new baseline. If it's a regression, reject it and investigate the cause.
Enabling Visual Regression
- Navigate to your Test Suite
- Click Run
- In the run options modal, toggle Enable Visual Regression
- Select your browser and click Start Run
Viewing Visual Results
After a run completes with visual regression enabled:
- Open the test run from the Runs page
- Click on any test case to open the step details
- Steps with visual comparisons show a three-panel view:
| Panel | Description |
|---|---|
| Baseline | The accepted reference screenshot |
| Current | The screenshot from this run |
| Diff | Highlighted pixel differences (pink/red areas) |
Diff Percentage
Each comparison shows a diff percentage badge:
- 0% — Perfect match, no visual changes
- 0.1% - 5% — Minor changes (font rendering, anti-aliasing)
- >5% — Significant visual change, review required
Managing Baselines
Accepting a New Baseline
When a visual change is intentional:
- View the diff in the step results
- Click Accept as Baseline
- The current screenshot replaces the old baseline
- Future runs compare against the new baseline
Rejecting a Change
When a visual change is unintended:
- View the diff in the step results
- Click Reject
- The original baseline is preserved
- Investigate and fix the visual regression in your code
Viewing All Baselines
To see all visual baselines for a project:
- Go to your project settings
- Navigate to the Visual Baselines section
- View, delete, or export baselines
How Pixel Comparison Works
AegisRunner uses the pixelmatch library for comparison:
- Screenshots are parsed as PNG images
- Each pixel is compared with a configurable threshold
- Anti-aliasing differences are handled gracefully
- Dimension mismatches are automatically normalized
- Diff images highlight changed pixels in bright pink/red
Best Practices
- Run baselines on a stable version of your app first
- Use consistent viewport sizes for reliable comparisons
- Accept new baselines after intentional design changes
- Combine visual regression with functional tests for comprehensive coverage
- Schedule visual regression runs after every deployment
- Ignore minor anti-aliasing differences — focus on layout and content changes
Limitations
- Dynamic content (timestamps, ads, animations) may cause false positives
- Font rendering may differ slightly across environments
- Screenshots are viewport-specific — changing viewport size creates new baselines
Related Documentation
- Running Tests - Execute test suites
- Debugging Tests - Fix failing tests
- API Testing - Test REST/GraphQL endpoints
- Scheduling Tests - Automate test runs