Getting started3 min readUpdated August 18, 2026

Visual regression testing with custom screenshots

Bring custom screenshots from any tool - native, mobile, or React Native - and diff them on every pull request. No Storybook, no browser, no SDK.

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 Screenshot project.

Follow https://uiverify.ai/docs/quickstart-screenshot to install the packages, add the config, and wire the GitHub Actions workflow. 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.

Ask me for my UIVERIFY_API_KEY when you need it, and I will add it as the CI secret.

Install the UI Verify skills for this project - the triage and economical-stories playbooks plus the deterministic-capture guide for this framework - so you can author cheap, stable stories and review builds yourself:
npx skills add uiverify/uiverify \
  --skill triage-visual-changes

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

One last step only I can do: install the UI Verify GitHub App from my project's setup page so the check and PR comment post. The first upload and baselines work without it, so it does not block getting started - just remind me to install it.

Some surfaces cannot be rendered in a browser: a native iOS or Android screen, a React Native app, a desktop or GPU app. For these, your own test harness already produces the pixels. A custom-screenshots project takes those finished PNGs, diffs each one against its baseline, and runs the same AI review and pull-request check as every other UI Verify project. UI Verify renders nothing here - you create the screenshots with whatever tool you like, we manage the baselines, the diff, and the review.

1. Get a project API key

2. Produce your screenshots and upload the directory

Run whatever already writes your screenshots (an XCUITest run, an Espresso run, a React Native snapshot step, or any script that saves PNGs) into one directory, then upload it. Each image's id is its path under that directory with the extension dropped, so checkout/mobile/cart.png becomes the stable key checkout/mobile/cart. Keep those paths steady across runs and a screen always diffs against its own baseline.

bash

# your own harness writes PNGs to ./screenshots
UIVERIFY_API_KEY=your_key npx -y uiverify@1.1.0 upload --screenshots ./screenshots

Your first upload becomes the baseline. Determinism is on your side of the line here: because UI Verify replays nothing, whatever your harness captured is exactly what gets diffed, so pin the device, the locale, and any live data at capture time.

3. 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: <your own step that writes finished PNGs to ./screenshots>
      - run: npx -y uiverify@1.1.0 upload --screenshots ./screenshots
        env:
          UIVERIFY_API_KEY: ${{ secrets.UIVERIFY_API_KEY }}

Keep fetch-depth: 0 so the baseline resolves against your real branch history.

4. 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 stories, 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 triage-visual-changes

5. 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 --transport http uiverify https://uiverify.ai/api/mcp \
  --header "Authorization: Bearer YOUR_UIVERIFY_API_KEY"

6. 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.

Upload everything, or only the screens you changed

You decide which screens to send. Upload the whole set every run and every screen is diffed. Upload only the screens a change actually touched and the rest keep their existing baselines untouched - a partial upload is its own skip. UI Verify does not second-guess that choice, so a screen you leave out is treated as unchanged. That is the same trade a graph-based skip makes: it saves work, and it puts the decision of what changed in your hands.

When to use custom screenshots instead of a rendered project

If your UI runs in a browser, a Storybook, Playwright, or Vitest project is the better fit: UI Verify renders it in a pinned browser, so determinism is handled for you. Reach for custom screenshots when there is no browser to render - native mobile, React Native, or a custom runtime - or when a tool you already run produces the screenshots and you just want them diffed and reviewed.

Keep going

Related skill

Triage a build from your agent

Bucket real regressions vs noise and accept baselines, over MCP.

Playwright 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