Screenshot Comparison Testing

Intermediate12 min

Implement visual regression testing with Playwright to detect unintended UI changes by comparing screenshots against golden baselines.

Prerequisites

-Playwright test project set up
-A visually stable web application

Steps

Write a visual comparison test

Create a test that captures and compares a full-page screenshot.

$ cat > tests/visual.spec.ts << 'EOF' import { test, expect } from '@playwright/test'; test('homepage visual regression', async ({ page }) => { await page.goto('/'); await expect(page).toHaveScreenshot('homepage.png', { fullPage: true, maxDiffPixelRatio: 0.01, }); }); test('button component visual', async ({ page }) => { await page.goto('/components'); const button = page.getByRole('button', { name: 'Submit' }); await expect(button).toHaveScreenshot('submit-button.png'); }); EOF

Generate baseline screenshots

Run the test for the first time to create golden reference images.

$ npx playwright test tests/visual.spec.ts --update-snapshots

Baseline screenshots are stored in a __snapshots__ directory next to your test file. Commit these to version control.

Run the visual comparison

Execute the tests to compare current screenshots against baselines.

$ npx playwright test tests/visual.spec.ts

Visual tests are sensitive to rendering differences across OS and browser versions. Always generate baselines in the same environment where tests run (typically CI).

Configure comparison thresholds

Adjust sensitivity settings in the Playwright config.

$ cat << 'EOF' // Add to playwright.config.ts use section: use: { screenshot: 'only-on-failure', }, expect: { toHaveScreenshot: { maxDiffPixelRatio: 0.01, threshold: 0.2, animations: 'disabled', }, }, EOF

Set 'animations: disabled' to prevent flaky tests caused by mid-animation screenshots.

Review visual diffs in the report

Open the HTML report to see side-by-side comparisons of failures.

$ npx playwright show-report

Full Script

full-script.sh

#!/bin/bash
# Playwright Visual Regression Testing
set -euo pipefail

echo "=== Visual Regression Test Workflow ==="

# Check for existing snapshots
SNAPSHOT_DIR="tests/__snapshots__"
if [ -d "$SNAPSHOT_DIR" ]; then
  SNAPSHOT_COUNT=$(find "$SNAPSHOT_DIR" -name '*.png' | wc -l)
  echo "Existing baselines: $SNAPSHOT_COUNT screenshots"
else
  echo "No baselines found. Will generate on first run."
fi

echo ""
echo "=== Running Visual Tests ==="
if [ "${1:-}" = "--update" ]; then
  echo "Updating baseline screenshots..."
  npx playwright test tests/visual.spec.ts --update-snapshots
  echo ""
  echo "New baselines generated. Review and commit them:"
  find "$SNAPSHOT_DIR" -name '*.png' -newer package.json 2>/dev/null | head -10
else
  npx playwright test tests/visual.spec.ts || true
  echo ""
  echo "=== View Report ==="
  echo "Run: npx playwright show-report"
fi

echo ""
echo "=== Commands ==="
echo "Run tests:       npx playwright test tests/visual.spec.ts"
echo "Update baselines: npx playwright test tests/visual.spec.ts --update-snapshots"
echo "View report:     npx playwright show-report"

FAQ

Discussion

Loading comments...

#!/bin/bash # Playwright Visual Regression Testing set -euo pipefail echo "=== Visual Regression Test Workflow ===" # Check for existing snapshots SNAPSHOT_DIR="tests/__snapshots__" if [ -d "$SNAPSHOT_DIR" ]; then SNAPSHOT_COUNT=$(find "$SNAPSHOT_DIR" -name '*.png' | wc -l) echo "Existing baselines: $SNAPSHOT_COUNT screenshots" else echo "No baselines found. Will generate on first run." fi echo "" echo "=== Running Visual Tests ===" if [ "${1:-}" = "--update" ]; then echo "Updating baseline screenshots..." npx playwright test tests/visual.spec.ts --update-snapshots echo "" echo "New baselines generated. Review and commit them:" find "$SNAPSHOT_DIR" -name '*.png' -newer package.json 2>/dev/null | head -10 else npx playwright test tests/visual.spec.ts || true echo "" echo "=== View Report ===" echo "Run: npx playwright show-report" fi echo "" echo "=== Commands ===" echo "Run tests: npx playwright test tests/visual.spec.ts" echo "Update baselines: npx playwright test tests/visual.spec.ts --update-snapshots" echo "View report: npx playwright show-report"