Getting started8 min readUpdated August 6, 2026

Playwright visual regression testing

Turn your Playwright tests into visual regression tests: capture a deterministic archive of the real pages they visit and diff it on every pull request. No Storybook.

Set it up with your coding agent

Paste this into Claude Code, Cursor, or any coding agent and it wires up UI Verify from these docs.

Set up UI Verify visual regression testing for my Playwright project.

Follow https://uiverify.ai/docs/quickstart-playwright to install the packages and add the config. https://uiverify.ai/llms-full.txt has the same docs as one plain-text reference if you want to read them without fetching each page.

Then run one build and upload it right now, locally - no CI or GitHub App needed for this - so my first build lands in the dashboard and we can confirm the setup works before wiring anything else. Use the upload command from the quickstart. Open the build page it prints in my browser so I can see the captured stories.

Ask me for my UIVERIFY_API_KEY when you need it for the upload.

Install the UI Verify skills for this project - the making-ui-changes playbook, the economical-visual-tests, triage, and check-visual-changes playbooks, plus the deterministic-capture guide for this framework - so you can change UI safely, author cheap stable stories, preview an edit's visual impact before pushing, and review builds yourself:
npx skills add uiverify/uiverify \
  --skill making-ui-changes \
  --skill economical-visual-tests \
  --skill triage-visual-changes \
  --skill check-visual-changes \
  --skill playwright-visual-testing

Then add a short rule to my AGENTS.md and CLAUDE.md so you read the making-ui-changes skill before any UI change from now on: `Before changing any component, page, or styles, read the making-ui-changes skill and follow it - reuse before you create, add/update the story or capture in the same change, check the blast radius on shared components, and prove the change with a visual test.`

After installing, restart this session (or reload the window) so the new skills load - you will not have them until I do.

Once that first build is in and looks right, wire the GitHub Actions workflow from the quickstart so every push is checked (add UIVERIFY_API_KEY as a repository secret), and remind me to install the UI Verify GitHub App from my setup page so the check and PR comment post - that's the one step only I can do, and it isn't needed for the first upload.

You do not need Storybook to do visual testing. If you already drive real pages with Playwright, @uiverify/playwright records an archive of what each page actually rendered, and UI Verify replays and screenshots that archive deterministically. This is how you visually test a Next.js app, a marketing site, or a live staging URL.

Prefer a complete, runnable example? The Playwright example drives a small app end to end and archives each step with this exact setup.

1. Get a project API key

2. Add the capture SDK and swap your import

Install the capture SDK, then swap your Playwright import so every test archives its final UI state. This import swap is the step that actually records the archive - installing the package alone does nothing. Add named mid-test checkpoints with uiVerify.snapshot().

bash

npm i -D @uiverify/playwright@1.0.2

e2e/checkout.spec.ts

import { test, expect } from "@playwright/test"; 
import { test, expect } from "@uiverify/playwright"; 

test("checkout", async ({ page, uiVerify }) => {
  await page.goto("/cart");
  await uiVerify.snapshot("cart"); // optional named mid-test checkpoint
  await page.click("#checkout");
  // final state is auto-archived at test end
});

3. Run your tests and upload the archive

Run your Playwright suite as usual. Each test writes what it rendered into ./uiverify-archive; then upload that directory. playwright install downloads the browsers once.

bash

npx playwright install     # one-time: download the browsers
npx playwright test        # writes ./uiverify-archive
UIVERIFY_API_KEY=your_key npx -y uiverify@1.4.0 upload --static-dir ./uiverify-archive

4. Catch a change locally

You do not need CI or a pull request to see a diff. Change something visible on a page - a color, a label - then re-run your Playwright tests and upload again on the same commit. UI Verify diffs the new build against your first one and flags what moved, so you see the review flow before wiring anything up.

bash

npx playwright test
UIVERIFY_API_KEY=your_key npx -y uiverify@1.4.0 upload --static-dir ./uiverify-archive

Open the build page it prints: the changed story is waiting in the review queue, where you accept or reject it. Accepting promotes the new screenshot to the baseline for that branch.

5. Wire it into CI

.github/workflows/visual.yml

name: UI Verify
on: pull_request

jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0   # full history so the baseline can be resolved
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - run: npx -y uiverify@1.4.0 upload --static-dir ./uiverify-archive
        env:
          UIVERIFY_API_KEY: ${{ secrets.UIVERIFY_API_KEY }}

npx playwright install --with-deps is required on a clean runner - without the browsers, playwright test fails before it captures anything. And keep fetch-depth: 0 so the baseline resolves against your real branch history.

This runs on every pull request, and the archive path always renders in full. On a busy repo, scope it to the PRs that can change the UI - see Run visual tests only on relevant pull requests.

6. Install the visual-testing skills

Give your coding agent the visual-testing playbooks so it can do the work in your repo: triage a build's changes, write economical visual tests, check an edit's visual impact before pushing, and keep captures deterministic. This installs just these skills, not the whole bundle. Restart the agent session afterward so they load.

bash

npx skills add uiverify/uiverify \
  --skill making-ui-changes \
  --skill economical-visual-tests \
  --skill triage-visual-changes \
  --skill check-visual-changes \
  --skill playwright-visual-testing

7. Review changes from your coding agent

Connect the UI Verify MCP and your agent can pull a build's changes into the conversation, look at each diff, read the AI judge's verdict, and accept the intended ones. Your project setup page has this command with the key already filled in; the header is your UIVERIFY_API_KEY. See Triage visual changes from your coding agent.

bash

claude mcp add --scope project --transport http uiverify https://uiverify.ai/api/mcp \
  --header 'Authorization: Bearer ${UIVERIFY_API_KEY}'

Project scope writes it to your committed .mcp.json, so the whole team gets it. The key is referenced as the UIVERIFY_API_KEY env var (single-quoted so your shell does not expand it at add time), not baked in, so the committed file never holds the secret: each teammate sets UIVERIFY_API_KEY in their environment and Claude Code expands it at runtime.

8. Install the GitHub App

Install the UI Verify GitHub App from your project's setup page and point it at your repo, so it can post a check and a comment on each pull request. This is the one step your coding agent cannot do for you. It does not block getting started: your first upload and baselines work without it, so add it when you want the results to show up on GitHub.

Capture every test, or only some

By default every Playwright test archives its final state, so playwright test captures your whole suite. @uiverify/playwright has no file filter of its own: you scope capture with Playwright itself. To capture only a subset, name those specs (for example *.visual.spec.ts) and select them with testMatch, a project, or a --grep tag.

bash

npx playwright test --grep @visual     # only tests tagged @visual
npx playwright test tests/visual       # only specs under one directory

To keep the suite running but exclude one test from capture, request the uiVerify fixture and call uiVerify.disableAutoSnapshot(). A test that fails, or that already called uiVerify.snapshot(), is never captured twice.

test("smoke check, no screenshot", async ({ page, uiVerify }) => {
  uiVerify.disableAutoSnapshot(); // opt this one test out of capture
  await page.goto("/health");
});

How is this different from Playwright's built-in toHaveScreenshot?

Playwright ships its own visual assertion, toHaveScreenshot: it screenshots the page and diffs it against a PNG committed next to the test. UI Verify runs the same pixel comparison, but over an archive your Playwright test captures once, and moves the baselines, the history, the review, and the judgment off your repo and CI. What changes:

The render is consistent across machines. toHaveScreenshot rasterizes wherever the test runs, so the same page produces different pixels on your Mac and the CI Linux box, and the baseline PNG is keyed to the OS (-chromium-darwin, -chromium-linux) - teams pin a Docker image to keep them in sync. UI Verify replays every capture in one fixed environment, so the pixels match no matter which machine ran the test. You still freeze in-app non-determinism - the clock, live data, a feature flag - in the test either way; the determinism checklist shows how.
No screenshot images in your repo. Every native baseline is a binary PNG committed to the repo, so it bloats history and merge-conflicts when two branches touch the same page. UI Verify stores one baseline per branch, resolved from git, with nothing in your repo.
The diff is on the pull request, not a downloaded artifact. A native failure writes the expected, actual, and diff PNGs into the Playwright report; to see them from a CI run you open the run, download the report artifact, unzip it, and open the images by hand - or you re-run and hope it was flake. UI Verify posts a check and the diff on the PR, with a review queue where a change is something you accept or reject.
It re-renders only what changed. toHaveScreenshot re-screenshots and re-diffs every test on every run, inside your CI. UI Verify captures the DOM and re-renders only the pages your pull request touched, on its own fleet, carrying the rest forward - so the pixel work, and the bill, scale with your change and not with the size of your suite. See skip unchanged.
Full history of every page, not just the latest PNG. UI Verify keeps every version, so you can see how a page looked build over build and when it changed. A committed baseline holds only the current image, and git cannot visually diff a binary, so with toHaveScreenshot that history is effectively gone. See baselines.
Updating a baseline is a click, and merging advances it for you. With toHaveScreenshot you regenerate the PNG on the right OS with --update-snapshots and commit it. UI Verify promotes the baseline for the branch when the pull request merges, through a GitHub webhook - nothing to regenerate, nothing to commit.
An AI judge and agent review. UI Verify classifies each change as a regression or an intended change and holds the pull request when it flags a regression, and it exposes the cropped before-and-after over MCP, so your coding agent reviews the pixels it changed without downloading an artifact or leaving the pull request. Playwright ships its own MCP and test agents, but they drive the browser and generate tests - they do not review visual diffs. See the AI judge, Triage with your agent, and the full UI Verify vs Playwright screenshots comparison.
Flaky changes are auto-ignored, not build-breaking. A change that does not reproduce on a re-render is dropped, so a flaky screenshot does not turn your pull request red and send you re-running the suite. See automatic flake detection.

Your coding agent can set this up and keep it deterministic - Set up visual testing wires the capture and CI, and Deterministic Playwright captures is the determinism checklist it applies.

Keep going

Related skill

Deterministic Playwright captures

Stop real-page diffs that flake without a real change.

Visual testing for agents

UI Verify captures your UI on every pull request and an AI judge tells an intended change from a real regression. See how it works.

Get started