Team Visual Regression with Percy

Playwright's built-in snapshots work well for solo developers. For teams, Percy adds a review layer — a web interface where developers can review visual diffs, approve changes, and collaborate before merging.

What Percy Adds

Cloud-hosted comparison: Snapshots are uploaded to Percy's servers and compared there. No snapshot files to commit or merge conflict to resolve.

Review UI: Percy provides a web interface showing before/after comparisons for every visual change. Reviewers can approve or reject changes with one click.

Branch comparison: Percy compares the current branch against the main branch baseline — so you always see what changed in this PR specifically.

Multi-browser snapshots: Percy captures snapshots in Chromium, Firefox, and WebKit simultaneously — one test run, cross-browser visual coverage.

Setting Up Percy with Playwright

Install the Percy SDK:

npm install --save-dev @percy/cli @percy/playwright

Update your tests to use Percy's snapshot function alongside your existing tests:

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

test('homepage visual', async ({ page }) => {
  await page.goto('/')
  await percySnapshot(page, 'Homepage')
})

Run tests with Percy:

npx percy exec -- npx playwright test

Percy uploads snapshots to the dashboard where your team can review them.

CI Integration

In your CI workflow (GitHub Actions, GitLab CI):

- name: Run visual tests
  env:
    PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
  run: npx percy exec -- npx playwright test

Percy blocks the PR from merging until all visual diffs are reviewed and approved. This ensures no unintentional visual change makes it to production.

Building a Review Process

Establish a review process for your team:

1. Developer opens a PR with visual changes
2. Percy captures snapshots and uploads diffs to the Percy dashboard
3. A designer or senior developer reviews the diffs
4. Intentional changes are approved; unintentional ones trigger a fix
5. PR merges only after all diffs are approved

This process adds visual quality control to every PR without requiring manual visual inspection.