Visual Regression Testing

1 The Hook — Why This Matters

A Wellington SaaS company pushes a CSS refactor late on a Friday afternoon. The PR passes all 230 functional tests — every button still clicks, every form still submits, every API call still returns 200. The team merges with confidence.

By Monday morning, a client in Sydney has emailed: the sidebar font is smaller than before, the hero image overflows on mobile, and the card borders on the dashboard have disappeared entirely. Three separate visual regressions, all introduced by one CSS refactor, all invisible to functional tests.

Functional tests verify that the app works. Visual regression tests verify that the app looks correct. These are not the same thing. A button can function perfectly while being rendered completely off the visible viewport. A form can submit successfully while the submit button has zero contrast. Visual regression tests are the safety net that catches the gap.

2 The Rule — The One-Sentence Version

The first run creates the baseline. Every subsequent run compares pixel-by-pixel against it. Deviations above your configured threshold fail the build — giving the team an explicit choice: accept the change (update the baseline) or fix the regression.

3 The Analogy — Think Of It Like...

4 Watch Me Do It — Step by Step

Playwright has built-in visual comparison via toHaveScreenshot(). No extra dependencies. Here is how to use it on a NZ SaaS dashboard.

import { test, expect } from '@playwright/test';

test('dashboard looks correct', async ({ page }) => {
  await page.goto('/dashboard');

  // Wait for dynamic content to settle before snapshotting
  await page.waitForLoadState('networkidle');

  // Mask dynamic elements (timestamps, avatars) so they don't cause false failures
  await expect(page).toHaveScreenshot('dashboard.png', {
    maxDiffPixels: 100,  // allow up to 100 pixel difference (anti-aliasing tolerance)
    threshold: 0.2,      // 20% per-pixel colour difference tolerance
    mask: [
      page.locator('[data-testid="last-login-time"]'),
      page.locator('[data-testid="user-avatar"]'),
    ],
  });
});

test('login page on mobile — iPhone 14', async ({ page }) => {
  await page.setViewportSize({ width: 390, height: 844 });
  await page.goto('/login');
  await page.waitForLoadState('networkidle');
  await expect(page).toHaveScreenshot('login-mobile.png');
});

// Store snapshots next to tests, keyed by OS and browser
export default defineConfig({
  snapshotPathTemplate: '{testDir}/__snapshots__/{testFilePath}/{arg}-{projectName}{ext}',
  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 100,
      threshold: 0.2,
    },
  },
});

# First run: creates baseline screenshots (commit these to the repo)
npx playwright test --update-snapshots

# Subsequent runs: fails if pixels differ beyond threshold
npx playwright test

# Update baselines for a specific test file only
npx playwright test visual.spec.ts --update-snapshots

For team-based review workflows, Percy (by BrowserStack) and Chromatic (by Storybook) provide a web dashboard where developers and designers can approve or reject visual diffs in a PR review. Percy integrates with Playwright in a few lines:

import { percySnapshot } from '@percy/playwright';

test('dashboard visual review', async ({ page }) => {
  await page.goto('/dashboard');
  await page.waitForLoadState('networkidle');
  // Sends snapshot to Percy dashboard for team approval
  await percySnapshot(page, 'Dashboard — desktop');
});

5 Tool Comparison — Which Visual Testing Approach?

In NZ, most mid-sized teams start with Playwright snapshots committed to the repo, then graduate to Percy when the design team wants to be involved in approvals. Chromatic is the right choice if you already have a Storybook component library.

6 Common Mistakes — Don't Do This

7 Now You Try — Prompt Lab

Write your visual regression plan below and the AI coach will review it.

8 Self-Check — Can You Actually Do This?

Click each question to reveal the answer. Three from three means you're ready for the interview round.

9 Interview Prep — What They'll Ask

10 Next Step

You now have the tools to catch both functional regressions and presentation-layer regressions. The next step is practice — apply both skills to realistic exercises in the Mid-Level practice section.