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.
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.
npx -y uiverify@1.10.0 loginYour 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.
# your capture script empties ./screenshots and writes fresh PNGs into it
./scripts/capture-screenshots.sh
npx -y uiverify@1.10.0 upload --screenshots ./screenshotsUpload 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.
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.
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
)
}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:
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 ./screenshotslayout: .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.
# re-run your capture script, then upload again
./scripts/capture-screenshots.sh
npx -y uiverify@1.10.0 upload --screenshots ./screenshotsOpen 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:
Wire UI Verify into CI for screenshots in this repo: fetch https://uiverify.ai/ci.md with curl and follow it.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 }}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.fetch-depth: 0 so the baseline resolves against your real branch history.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.
npx skills add uiverify/uiverify \
--skill making-ui-changes \
--skill triage-visual-changes \
--skill check-visual-changes6. 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.
claude mcp add --scope project --transport http uiverify \
https://uiverify.ai/mcpThen 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