UI Verify

---

UI Verify とは？

UI Verify は、CI に組み込めるホスト型ビジュアルテストサービスです。各 PR で次の処理を行います。

1. キャプチャ：Storybook のストーリー、既存の Playwright または Vitest のブラウザーモードテストにドロップイン式のキャプチャ SDK を追加したもの、あるいは独自のハーネスで生成した完成済みスクリーンショット（ネイティブ、モバイル、React Native）を直接アップロードしたものから、UI をキャプチャします。
2. レンダリングと差分比較：すべての状態をクラウド上で、デフォルトブランチのベースラインと比較します。
3. 結果を報告：判定結果を GitHub のチェックとして返し、それに基づいて PR を制御します。
4. トリアージ：コーディングエージェント（Claude Code、Codex など）が実際のリグレッションと見た目だけのノイズを分類し、すべて MCP 経由で新しいベースラインをまとめて承認できます。

このリポジトリには、オープンソースのクライアントパッケージ、つまり あなたの リポジトリ内で動作するものが含まれています。レンダリング、差分比較、判定はすべてサーバー側で行われます。これらのパッケージが行うのは、バンドルの作成、HTTP 経由でのアップロード、ステータスの取得だけです。そのため、どのパッケージも安心して内容を確認、フォークし、セルフホスト環境で利用できます。

クイックスタート

# 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

すでにスクリーンショットがある場合は？ハーネスですでにスクリーンショットを生成しているなら（Detox、Maestro、ネイティブのスナップショットテストなど、どのようなものでも）、PNG を直接アップロードできます。Storybook もレンダリングも必要ありません。UI Verify は同じように差分を比較し、判定して、ベースラインを管理します。

npx uiverify upload --screenshots ./screenshots

ネイティブ、モバイル、React Native のプロジェクトでは、この方法で UI Verify を利用します。各画像はディレクトリ内のパスをキーとしているため、ビルドごとに同じ画面が同じベースラインに対応します。変更した画面だけをアップロードし、残りはそのまま引き継ぐこともできます。

エージェントから操作したい場合は？スキルをインストールして（下記参照）、/uiverify:setup-visual-testing を実行してください。キャプチャ方法を検出し、CI を設定して、最初のストーリーを作成します。

コーディングエージェントによる編集中のチェック：uiverify check

エージェントは編集中に、変更しているストーリーだけをレンダリングし、CI で使われている実際のベースラインと比較できます。CI を待たずに「これでパスするか」を確認できます。

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

指定したストーリー（繰り返し指定できる --story、glob、または正確な ID）のみをレンダリングし、PR チェックは投稿せず、CI のベースラインも変更しません。changed の結果は参考情報であり（終了コード 0）、UI Verify MCP の get_build / render_diff_image でピクセルを確認してから、ダッシュボードまたは accept_build で承認し、ブランチ単位のプレビューベースラインを設定してください。そうすれば、承認済みの変更が次回のチェックで再び指摘されることはありません。main のベースラインを更新できるのは CI だけです。

パッケージ

パッケージ	インストール	概要
uiverify	npm i -D uiverify	CLI です。uiverify upload は CI 用アップローダーです（Storybook バンドル、Playwright／Vitest アーカイブ、または完成したスクリーンショットのディレクトリに対応）。レンダリングの進行状況をストリーミングし、ビジュアル判定を終了コードに反映します。uiverify check はエージェントの編集ループ用チェックです。指定したストーリーのみを実際の CI ベースラインと照合してレンダリングし、チェックを投稿したり、ベースラインを移動したりしません。
@uiverify/playwright	npm i -D @uiverify/playwright	Playwright キャプチャ SDK です。@playwright/test をこれに置き換えると、各テストで最終的な UI 状態（シリアライズされた DOM ＋ リソースバイト）がアーカイブされ、UI Verify で再生して差分を確認できます。
@uiverify/vitest	npm i -D @uiverify/vitest	Vitest キャプチャ SDK です。Vitest の設定に uiverifyPlugin() を追加すると、ブラウザモードの各テストで最終的な DOM（シリアライズされた DOM ＋ リソースバイト）がアーカイブされ、UI Verify で再生して差分を確認できます。名前付きスナップショットを取得する場合は、代わりに takeSnapshot() を使います。
@uiverify/skills	npx skills add。下記を参照	エージェントスキルです。コーディングエージェントがリポジトリ内で実行する SKILL.md ワークフローにより、ビジュアルテストのセットアップ、効率的かつ決定論的なストーリーの作成、ビルドのトリアージを行います。Claude Code または Cursor のプラグイン、あるいは Gemini CLI の拡張機能として使用すると、UI Verify MCP サーバーにも接続します。
@uiverify/workflow-skills	Claude Code プラグイン。下記を参照	UI Verify の開発に使用しているエージェント開発ループです。factory、design、review-loop、e2e-verify、babysit-pr と、それを調整するスキルが含まれます。

エージェントスキル

1 つのコマンドで、任意のコーディングエージェントにスキルをインストールできます（skills.sh）。

npx skills add uiverify/uiverify

Claude Code、Cursor、Codex、Copilot、Gemini、およびスキルフォルダーを読み込むあらゆるエージェントで動作します。個別のスキルを選ぶには --list を追加し、最新のスキルを取得するには npx skills update を実行してください。

または、Claude Code ではプラグインとしてインストールすると、更新が自動的に適用されます。

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

どちらの場合も、スキル名で呼び出します。/uiverify:setup-visual-testing、/uiverify:triage-visual-changes などを使用できます。全スキルの一覧と手動でコピーして使う方法については、packages/skills を参照してください。

Gemini CLI では、同じスキルと MCP サーバーを拡張機能としてインストールし、一度ログインしてください。

gemini extensions install https://github.com/uiverify/uiverify

Gemini CLI のセッションで /mcp auth uiverify を実行し、ブラウザーで UI Verify にログインしてください。

UI Verify の開発に使用しているエージェント開発ループ（factory、design、review-loop、e2e-verify、babysit-pr）は、同じマーケットプレイスで提供されるもう 1 つのプラグインです。/plugin install uiverify-workflow@uiverify を実行してから、/uiverify-workflow:factory を実行してください。packages/workflow-skills を参照してください。

MCP によるトリアージ

UI Verify MCP サーバーに接続すると、コーディングエージェント（Claude Code、Cursor、Codex など）がプルリクエストの UI 変更を会話に取り込み、各差分を確認し、AI 判定の結果を読み取り、意図したベースラインを承認できます。ターミナルを離れる必要はありません。

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

上記のプラグインをインストールした場合は、このサーバーにすでに接続されているため、コマンドを実行せずに /mcp からログインしてください。そうでない場合は、追加後に Claude Code を再起動し、/mcp を実行して uiverify を選び、ブラウザーで UI Verify にログインしてください。ログインは一度だけでよく、所属するすべてのチームのすべてのプロジェクトで接続が利用できます。--scope project を指定すると、コミット済みの .mcp.json に設定が書き込まれるため、チーム全体で利用できます。このファイルに秘密情報は含まれません。各メンバーが自分のアカウントでログインするためです。Cursor では、.cursor/mcp.json に { "mcpServers": { "uiverify": { "url": "https://uiverify.ai/mcp" } } } を追加し、MCP 設定からログインしてください。Gemini CLI では、上記の拡張機能が接続を行い、/mcp auth uiverify でログインできます。詳しいガイド：コーディングエージェントから視覚的な変更をトリアージする。

サーバーはリモート（ストリーミング可能な HTTP）で、インストールや実行は不要です。次のツールを提供します。

ツール	機能
list_projects	アクセス可能なプロジェクトを一覧表示します。複数ある場合は、渡す projectId も確認できます
list_builds	UI Verify の最近のビルドを一覧表示します
get_build	ビルドで変更された内容を取得します
list_build_stories	ステータス別にビルドのストーリーをページ単位で取得します
get_pr_changeset	PR がベースブランチと比較して UI に加える変更を取得します
list_pr_stories	PR とベースブランチの変更セットを種類別にページ単位で取得します
get_diff	画像 URL を含む、ストーリーごとの差分の詳細を取得します
render_diff_image	ストーリー画像の実際のピクセルデータを取得します
review_diff	1 つのストーリーの変更を承認、拒否、または無視します
accept_build	ビルド内の変更されたすべてのストーリーを承認します

例

examples/ に、キャプチャ方法ごとの完全で実行可能なプロジェクトがあります。フォルダーをコピーしてプロジェクト API キーを追加すれば、動作します。

例	キャプチャ方法
examples/storybook	Storybook のストーリー（SDK 不要、upload --static-dir）
examples/vitest	@uiverify/vitest を使った Vitest のブラウザーモードテスト
examples/playwright	@uiverify/playwright を使った Playwright のエンドツーエンドテスト
examples/react-native	完成したスクリーンショット（ネイティブ／モバイル／React Native、upload --screenshots）

最初の 3 つは同じ Shoppy ストアフロントの一部をキャプチャします。React Native の例は、Maestro で操作する小規模な Expo アプリです。各フォルダーには独自の CI ワークフローがあります。

開発

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

CLI には UIVERIFY_API_KEY が必要です。デフォルトでは https://uiverify.ai に接続します（セルフホストまたはローカル開発の場合は、--api-url／UIVERIFY_API_URL で変更できます）。内部の仕組みについては、各パッケージの README と DEVELOPMENT.md を参照してください。

ライセンス

MIT © UI Verify