UI Verify

Visual testing for agents

Catch unintended UI changes on every pull request. UI Verify renders your components in the cloud, diffs them against a baseline, and lets a coding agent triage what actually changed.

uiverify.ai  ·  GitHub  ·  CLI  ·  Playwright SDK  ·  Vitest SDK  ·  Skills

What is UI Verify?

UI Verify is a hosted visual-testing service that plugs into your CI. On each PR it:

1. Captures your UI, from Storybook stories, from your existing Playwright or Vitest browser-mode tests via a drop-in capture SDK, or from finished screenshots your own harness already produces (native, mobile, React Native) uploaded straight for diffing.
2. Renders & diffs every state in the cloud against the baseline from your default branch.
3. Reports the verdict back as a GitHub check, and gates the PR on it.
4. Triages: a coding agent (Claude Code, Codex, and others) buckets real regressions vs. cosmetic noise and can accept new baselines in bulk, all over MCP.

This repository holds the open-source client packages, everything that runs in your repo. All rendering, diffing, and judging happens server-side; these packages only build a bundle, upload it over HTTP, and read back status, so each is safe to read, fork, and self-host against.

Quickstart

# 1. Install the CLI in your project
npm i -D uiverify

# 2. Point it at your account
export UIVERIFY_API_KEY=...        # from uiverify.ai

# 3. Build your Storybook, then upload; the exit code reflects the visual verdict
npm run build-storybook
npx uiverify upload --static-dir storybook-static

Already have screenshots? If your harness already produces them (Detox, Maestro, native snapshot tests, anything), upload the PNGs directly, no Storybook and no rendering required. UI Verify diffs, judges, and baselines them just the same:

npx uiverify upload --screenshots ./screenshots

This is how native, mobile, and React Native projects use UI Verify: each image is keyed by its path under the directory, so a screen maps to the same baseline every build, and you can upload only the screens you changed and carry the rest forward.

Prefer to drive it from your agent? Install the skills (below) and run /uiverify:setup-visual-testing. It detects your capture path, wires CI, and writes the first stories for you.

Mid-edit checks for coding agents: uiverify check

While an agent is editing, it can render just the stories it is touching and diff them against the real CI baseline on the fleet - a "would this pass" answer without waiting for CI:

npm run build-storybook
npx uiverify check --story 'components-button--*' --static-dir storybook-static

It renders only the stories you name (repeatable --story, globs or exact ids), posts no PR check, and never moves a CI baseline. A changed result is informational (exit 0) - review the pixels over the UI Verify MCP (get_build / render_diff_image) and accept in the dashboard or with accept_build to set a branch-scoped preview baseline, so your own accepted changes stop re-flagging on the next check. CI stays the only path to a main baseline.

Packages

Agent skills

Install the skills into any coding agent with one command (skills.sh):

npx skills add uiverify/uiverify

Works in Claude Code, Cursor, Codex, Copilot, Gemini, and any agent that reads a skills folder. Add --list to pick individual skills, and run npx skills update to pull the latest.

Or, on Claude Code, install as a plugin so updates arrive automatically:

/plugin marketplace add uiverify/uiverify
/plugin install uiverify@uiverify

Either way, invoke them by name: /uiverify:setup-visual-testing, /uiverify:triage-visual-changes, and more. See packages/skills for the full list and a copy-in-by-hand alternative.

Triage over MCP

Connect the UI Verify MCP server and your coding agent (Claude Code, Cursor, Codex, and others) can pull a pull request's UI changes into the conversation, look at each diff, read the AI judge's verdict, and accept the intended baselines - without leaving the terminal.

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

--scope project writes it to your committed .mcp.json so the whole team gets it; the key is referenced as the UIVERIFY_API_KEY env var, never baked in. Your project setup page has this command with the key filled in. Full guide: Triage visual changes from your coding agent.

The server is remote (streamable HTTP) - there is nothing to install or run. It exposes:

Examples

Complete, runnable projects under examples/ — one per capture path. Copy a folder, add a project API key, and it works.

The first three capture a slice of the same Shoppy storefront; the React Native one is a small Expo app driven by Maestro. Each folder has its own CI workflow.

Development

pnpm install
pnpm -r build        # CLI builds dist/uiverify.js, playwright builds dist/
pnpm -r test
pnpm -r typecheck

The CLI requires UIVERIFY_API_KEY and talks to https://uiverify.ai by default (override with --api-url / UIVERIFY_API_URL for self-host or local dev). See each package's README and DEVELOPMENT.md for internals.

License

MIT © UI Verify