Skip to content

Visual Regression Testing

In one line

Visual regression testing screenshots your UI and compares to baseline — catches unintended visual changes automatically.

In simple words

Visual regression testing catches visual bugs that functional tests miss. It takes screenshots of your UI and compares them pixel-by-pixel against a baseline (known-good) screenshot.

What visual regression catches:

  • Layout shifts from CSS changes
  • Color changes from theme updates
  • Missing or misplaced elements
  • Responsive layout breaks at different viewport sizes
  • Font rendering differences
  • Overflow or clipping issues

How it works:

  1. Baseline — take screenshots of the current (correct) UI
  2. After changes — take new screenshots
  3. Compare — pixel-by-pixel diff, highlight differences
  4. Review — a human reviews the diff (some changes are intentional)
  5. Update baseline — if changes are intentional, update the baseline

Challenges:

  • False positives — anti-aliasing, fonts, rendering differences across browsers
  • Dynamic content — dates, ads, random data cause false diffs (mock them)
  • Maintenance — baselines need updating when UI intentionally changes

Tools: Percy, Chromatic, Applitools, Storybook + playwright, reg-suit.

Example

javascript
// Playwright visual regression test
import { test, expect } from '@playwright/test';

test('homepage looks correct', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveScreenshot('homepage.png', {
    maxDiffPixelRatio: 0.01, // allow 1% pixel difference
    threshold: 0.2,          // per-pixel tolerance
  });
});

test('product card renders correctly', async ({ page }) => {
  await page.goto('https://example.com/product/1');
  const card = page.locator('.product-card');
  await expect(card).toHaveScreenshot('product-card.png');
});

// First run: creates baseline screenshots
// Subsequent runs: compares to baseline
// If diff > threshold: test FAILS with visual diff shown
// To update baseline: npx playwright test --update-snapshots

Playwright takes a screenshot and compares to baseline. If pixels differ beyond threshold, the test fails showing a visual diff. Update baselines with --update-snapshots when changes are intentional.

Common confusions

  • Confused with: snapshot testing

    The difference: Snapshot testing (Jest) serializes component output to a text/JSON string and compares — it checks the structure/props, not pixels. Visual regression testing compares actual rendered screenshots pixel-by-pixel — it checks what users see. Snapshot tests are fast but miss visual issues (CSS, layout); visual tests are slower but catch real visual bugs.

Related terms

Related Resources

Related Lessons

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to glossary