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  ·  Skills

uiverify

The CI uploader for UI Verify. uiverify upload uploads your prebuilt Storybook bundle (or a Playwright/Vitest archive, or a directory of finished screenshots), streams render progress (Rendered X / N), and reflects the visual verdict (changed / failed) in its exit code so CI can gate on it.

Usage

Build your Storybook first, then point --static-dir at its output:

npm run build-storybook -- --stats-json
UIVERIFY_API_KEY=... npx uiverify upload --static-dir storybook-static

--stats-json writes Storybook's dependency graph, which lets UI Verify skip the stories your change can't affect (see Skipping unchanged stories).

Or upload finished screenshots your own harness already produced (native, mobile, React Native, anything) with --screenshots. No Storybook and no server-side rendering: UI Verify diffs, judges, and baselines the PNGs directly.

UIVERIFY_API_KEY=... npx uiverify upload --screenshots ./screenshots

Each image is keyed by its path under the directory with the extension dropped, so a screen maps to the same baseline every build. Upload only the screens you changed and the rest carry forward (the client is the source of truth for what changed, the same trade-off TurboSnap and Argos make).

Options

• --static-dir <dir>: the prebuilt Storybook static directory to upload (e.g. storybook-static).
• --screenshots <dir>: a directory of finished PNG/JPG screenshots to upload directly (native / mobile / React Native), instead of --static-dir. Skips rendering entirely; images are keyed by their path under the directory.
• --working-directory <dir>: the repo checkout (git metadata + the bundle live here).
• --api-url <url>: UI Verify API URL (default https://uiverify.ai; or UIVERIFY_API_URL).
• --auto-accept-changes: accept this build's changed snapshots as the new baseline (no review). Typically used on merges to your default branch.
• --exit-zero-on-changes: detect but don't block. A changed (needs-review) verdict exits 0 and stays pending review; failed still exits non-zero.
• --render-all: render every story, even ones the dependency graph shows your change can't reach, and even if this exact commit already passed.
• --only-changed: removed and ignored with a warning, so an old workflow keeps working. Skipping unchanged stories is the default whenever the bundle carries a dependency graph (for a Vitest archive, one from @uiverify/vitest 1.6.0 or later); see Skipping unchanged stories below.
• --strict / --no-strict: whether an operational failure (missing key, missing bundle, network error) fails the job. Strict by default.

Exit codes: 0 success (or an operational failure under --no-strict), 1 the visual verdict or an operational failure under strict, 2 a malformed invocation (unknown option, boolean given a value, or stray token). Exit 2 ignores --no-strict - that flag means "don't fail my job if the upload breaks", not "run with arguments I didn't mean".

Skipping unchanged stories

When the bundle carries a dependency graph (preview-stats.json at the root of the upload directory; for a Vitest archive, one written by @uiverify/vitest 1.6.0 or later), UI Verify renders just the stories your change could have affected and carries every other baseline forward at a fraction of a snapshot each, so a one-component PR costs far less than a full suite. This is the default; there is nothing to turn on. The CLI works out which files changed with git diff in your checkout and sends only the paths.

Where the graph comes from:

• Storybook: build with --stats-json (Storybook 8+; --webpack-stats-json on 7.x).

  npm run build-storybook -- --stats-json
  UIVERIFY_API_KEY=... npx uiverify upload --static-dir storybook-static

• Vitest: @uiverify/vitest 1.6.0 and later writes the graph into the archive itself (keep uiverifyPlugin() in your root Vitest config). Tests whose imports git can't follow, such as bundler output or gitignored generated code, are left out of the graph and always render; the test run says how many and why.

• Playwright or another archive: add a preview-stats.json to the archive directory yourself, in the module graph format.

Without a graph there is no fallback: every story renders, deliberately, since a filename heuristic can't tell that a page story imports the component you changed. For Storybook and Vitest the upload log says so on every run (unless you passed --render-all) and names the way to get a graph. Screenshot uploads never skip server-side; upload only the screens you changed instead.

Uploading from a checkout with uncommitted edits is safe. The CLI counts files that differ from the commit as changed (outside CI, untracked files that aren't ignored too), so what they affect renders. Such a build can still be reviewed and accepted, but later builds don't skip stories based on it.

To render everything for one build, pass --render-all.

Environment

• UIVERIFY_API_KEY (required): your project key. Only ever sent in the Authorization header, and redacted from all logs.
• UIVERIFY_API_URL: override the default API URL (self-host / local dev).

License

MIT