All docs
Getting started10 min readUpdated

Set up visual testing with custom screenshots

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

Paste this into Claude Code, Cursor or any coding agent, in your repo. It reads our install guide, signs you in and sets everything up from there.

Set up UI Verify for screenshots in this repo: fetch https://uiverify.ai/install.md with curl and follow 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.

This page is the setup. For what mobile app visual regression testing is and how UI Verify compares to Maestro, snapshot libraries and hosted services, see Mobile app visual regression testing.
Prefer a complete, runnable example? The React Native example is a small Expo app that produces a screenshot per screen with Maestro and uploads them with this exact command.

1. Sign in

Sign in once on your machine. The command prints a link and a short code, opens the link in your browser when it can, and waits while you sign in (or sign up) and approve. No project key goes in your commands or your repository.

bash
npx -y uiverify@1.10.0 login

Your first upload creates your project, named after your repository, and your first team, named after the repository's owner. If you made a project on the website first, pass --project <team>/<slug> to that upload so it goes there. If the sign-in can't finish, set UIVERIFY_API_KEY to the project key from your project's settings instead (under API keys). No project yet? Create one first at uiverify.ai/onboarding, under "Create a project", and its settings show the key. In CI, store that key as a repository secret named UIVERIFY_API_KEY. A repo with several apps? See Several apps in one repo.

2. Produce your screenshots and upload the directory

Run whatever already writes your screenshots (an Espresso run, a Maestro flow, a React Native snapshot step, or any script that saves PNGs) into one directory, then upload it. For iOS, use the swift-snapshot-testing recipe below. 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. When your screens span several folders, the build page's Screenshots grid groups them by folder, so checkout/mobile/cart sits under a checkout / mobile header.

bash
# your capture script empties ./screenshots and writes fresh PNGs into it
./scripts/capture-screenshots.sh
npx -y uiverify@1.10.0 upload --screenshots ./screenshots

Upload only what a capture you just ran produced, into a folder that only the capture writes to, that git ignores and that it empties first, and keep that capture as a script: the same command then makes every build, locally and in CI. Don't upload PNGs that already sit in the repo, such as a snapshot library's committed reference images. They are whatever some past run saved, and no command reproduces them. Start with your app's main screens on one device, in one theme and one language; add themes, languages and text sizes later, since each one multiplies every build.

Your first upload shows every screen as new: accept it and it 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. There is no page for UI Verify to mask regions on, so hide or freeze anything that changes between runs before your harness takes the screenshot.

iOS and Swift apps: use swift-snapshot-testing

For a SwiftUI or UIKit app, the simplest way to produce the screenshots is swift-snapshot-testing from Point-Free. It renders a view inside an ordinary unit test on the iOS simulator, so there is no UI test target, no app launch and no status bar to freeze. Add the package to your test target, then add this helper. It writes one PNG per call and never fails the test, because the baseline lives in UI Verify, not in your repo.

AppTests/UIVerifyScreenshot.swift
import Foundation
import SnapshotTesting
import SwiftUI

func uiverifyScreenshot<V: View>(_ view: V, named name: String, folder: String? = nil, testName: String = #function) {
  let root = ProcessInfo.processInfo.environment["UIVERIFY_SCREENSHOTS_DIR"]
    ?? NSTemporaryDirectory() + "uiverify-screenshots"
  // a "/" in name is flattened to "-" by swift-snapshot-testing, so the folder goes on the directory
  let dir = folder.map { "\(root)/\($0)" } ?? root
  // record: .all always writes the PNG; verifySnapshot returns a message instead of failing the test
  _ = verifySnapshot(
    of: view,
    as: .image(layout: .device(config: .iPhone13)),
    named: name,
    record: .all,
    snapshotDirectory: dir,
    testName: testName
  )
}
AppTests/CheckoutScreenshots.swift
import XCTest
@testable import App

final class CheckoutScreenshots: XCTestCase {
  func testCart() {
    uiverifyScreenshot(CartView(items: .fixture), named: "cart")
  }

  func testCartEmpty() {
    uiverifyScreenshot(CartView(items: []), named: "empty", folder: "checkout")
  }
}

Each call saves <test name>.<name>.png, so testCart uploads as the key testCart.cart. Pass folder: to save a screen in a subfolder: testCartEmpty uploads as checkout/testCartEmpty.empty, and the folder becomes its group on the build page. Run the tests on a simulator and point the helper at ./screenshots. xcodebuild passes any variable prefixed with TEST_RUNNER_ into the test process, and a simulator test can write straight to a folder on your Mac:

bash
TEST_RUNNER_UIVERIFY_SCREENSHOTS_DIR="$PWD/screenshots" \
  xcodebuild test -scheme App -destination 'platform=iOS Simulator,name=iPhone 16'
npx -y uiverify@1.10.0 upload --screenshots ./screenshots
Keep the pixels stable from run to run: use the same Xcode version and simulator runtime every time (rendering differs between iOS versions), pass fixed data instead of live network calls, and set the date and locale explicitly in the views you capture. layout: .device(config: .iPhone13) already fixes the screen size and traits, whichever simulator runs the test. In CI, run the job on a macOS runner (runs-on: macos-15), since the iOS simulator does not run on Linux. Save the xcodebuild run as your capture script, after a line that deletes the PNGs the helper wrote last time, so every upload carries only what that run captured.

3. Catch a change locally

You do not need CI or a pull request to see a diff. Change something visible in a screen - a color, a label - then regenerate your screenshots 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
# re-run your capture script, then upload again
./scripts/capture-screenshots.sh
npx -y uiverify@1.10.0 upload --screenshots ./screenshots

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

4. Wire it into CI

Paste this one line into your coding agent and it adds the workflow below and the repository secret for you (it asks for your project key: copy it from your project's settings, under API keys). Or add the workflow yourself:

Paste into your coding agent
Wire UI Verify into CI for screenshots in this repo: fetch https://uiverify.ai/ci.md with curl and follow it.
.github/workflows/visual.yml
name: UI Verify
on:
  push:
    branches: [main] # your default branch: its builds are the baseline every PR compares against
  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 capture script: empties ./screenshots and writes fresh PNGs into it>
      - run: |
          npx -y uiverify@1.10.0 upload --screenshots ./screenshots \
            ${{ github.event_name == 'push' && '--auto-accept-changes' || '' }}
        env:
          UIVERIFY_API_KEY: ${{ secrets.UIVERIFY_API_KEY }}
The push trigger on your default branch is required, not optional. Builds there keep the baseline every PR compares against up to date, and they are what lets a PR render only the stories it touches. A workflow that runs only on pull requests sees every story as new on every PR and renders all of them. --auto-accept-changes applies only to that push run: it accepts what you merged, so the baseline moves forward without a second review, while pull requests still wait for yours. Change [main] to whatever your default branch is (master, develop), or the trigger never fires.
Keep fetch-depth: 0 so the baseline resolves against your real branch history.
Close the accept loop before you call setup done. The upload job exits non-zero on an unreviewed build, so after you accept the changes UI Verify flips its own check green but the failed Actions job stays red until it re-runs, and every accepted PR looks broken. Always set up one of the two: make UI Verify: <slug> a required status check, or add the auto-rerun workflow that clears the job the moment you accept. Both are in Require the check and auto-clear the CI job.

5. 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 triage-visual-changes \
  --skill check-visual-changes

6. 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. See Triage visual changes from your coding agent.

bash
claude mcp add --scope project --transport http uiverify \
  https://uiverify.ai/mcp

Then log in once: restart Claude Code, run /mcp, pick uiverify, and log in to UI Verify in your browser. After that the agent can reach every project in every team you are a member of. Project scope writes the server to your committed .mcp.json, so the whole team gets it, and the file holds no secret: each teammate logs in with their own account. Using Cursor, Codex, or another client? See UI Verify MCP server for coding agents for its setup.

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

Do I have to upload every screenshot on every run?

No. 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 keeps its baseline as it is. 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 should I use custom screenshots instead of a rendered project?

Use 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. If your UI runs in a browser, a Storybook, Playwright, Vitest, or Bun project is the better fit: UI Verify renders it in a pinned browser, so determinism is handled for you.

Visual testing for agents

UI Verify is visual regression testing for Playwright, Storybook, Vitest and Bun. Your coding agent sees what its UI change did and fixes it before it ships. See how it works.

Get started