Getting started2 min readUpdated July 30, 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.

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.

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

// swap @playwright/test -> @uiverify/playwright: every test now also archives its UI
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@latest upload --static-dir ./uiverify-archive

4. Install the GitHub App

Install the GitHub App from your project settings and point it at your repo, so UI Verify can post a check and a comment on each pull request. Uploads still work without it, but nothing shows up on GitHub.

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@v4
        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@latest 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.

Why archive-replay instead of a live screenshot?

A screenshot taken against a live page flakes on anything non-deterministic - live data, the clock, feature flags, a third-party widget that loads a beat late. Archive-replay bakes the page into a static archive at record time, then replays it identically on every run, so a diff means a real change and not a coincidence of timing. See Fix flaky visual tests.

Your coding agent can wire this up for you - the Playwright visual testing skill packages the fixture setup and the determinism checklist.

Keep going

Related skill

Deterministic Playwright captures

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

Storybook visual regression testing

How visual regression testing works

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