Visual verify
バージョン: 1.1.0。1.0.0 より前のバージョンはこのリポジトリで追跡されません。
実際に動作しているアプリをヘッドレスブラウザで確認し、見た内容を正直に報告します。 2つのモードがあります:
- Verify (デフォルト) — 現在の状態のスクリーンショットを1枚(または数枚)撮影し、自分で読み取って、機能が正しくレンダリングされているか、修正が機能したか、特定の幅でレイアウトが正しいかを確認します。
- Before/after — 視覚的な変更がある場合、変更をオフとオンに切り替えて、ラベル付きのBEFORE/AFTER比較画像を1枚生成します。
- Touch (iOS / Android) — 電話をエミュレートし、指でタップ&ドラッグし、タッチターゲットのサイズを監査します。詳しくは以下「モバイルタッチチェック」を参照。
ユーザーのリクエストからモードを選択してください。「これで正しく見えるか / 動作しているか / 電話の幅で表示して」→ Verify。「Before/after / これで視覚的に修正されたか」→ Before/after。
ユーザーが依頼したら、実行する
ユーザーが視覚的に確認してほしいと依頼した場合(またはスクリーンショット / 見た目を確認してほしいと言った場合)、そのリクエストは実行開始の合図です — 完全なチェックを自分で実行してください: キャプチャ、画像の読み取り、正しいかどうかを明確に述べてください。提案だけで終わらせないでください。
変更のたびに依頼なしで自分から実行しないでください。ブラウザを駆動し画像を読み取るため、トークンを消費します。依頼されていない視覚的な変更の後は、提案するだけに留めても構いません(「ビフォー/アフター比較画像を作成しましょうか?モバイル、デスクトップ、または両方?」)そして、ユーザーに決定させてください。
確認した内容を毎回表示する
ユーザーはファイルを開かなくても結果を確認できる必要があります。確認した内容を報告する返信では、確認した機能ごとにafter画像を表示してください — 機能ごとに1つの画像、つまり3つ確認した場合は少なくとも3つの画像です。各画像の横に、それが何を示し、正しいかどうかを示す1行のキャプションを配置してください(例: 「削除確認ダイアログ、電話幅 — Cancelにフォーカス」)。
- 画像はMarkdownと絶対パスを使用してインライン表示します:
(クライアントがレンダリングする場合)。それ以外の場合は添付してください(例: SendUserFile)。パスも常に示してください。 - 最も明確なショットを選んでください: ページ全体だと埋もれてしまう機能は、トリミングまたはクリップしてください。
- ビフォー/アフターの場合は、比較画像を表示してください。
- 何かを正直に表示できない場合(システムUI、セーフエリアなど)、誤解を招く画像を表示する代わりに、その旨を述べてください。
キャプチャしたものは必ず確認する
スクリーンショット自体が成果物ではありません — あなたの検証済みの判断が成果物です。報告する前に、キャプチャしたすべての画像を読み取り、比較画像を送信する前に、それが実際に自分が主張する内容を示していることを確認してください。期待した内容が表示されていない場合は調査してください。読んでいないショットで成功を報告しないでください。
適切なビューポートを選択する — これは重要です
レスポンシブバグは、特定の幅でのみ再現することがよくあります。ユーザーのデバイスに合わせてください。 ユーザーがスクリーンショットを送信した場合は、CSS幅を導き出します:
css_width = screenshot_pixel_width / devicePixelRatio
最新のiPhoneはDPR 3です(例: 1320px幅のスクリーンショット ⇒ 440 CSS px; Pro Maxクラス)。一般的なAndroidはDPR約2.6~3です。不明な場合は、複数の幅(例: 320, 360, 390, 440)をスイープしてください — スクリーンショットスクリプトではこれが容易です。タッチ/モバイルエミュレーションの場合は--mobileを渡してください。すべての幅に適用される一般的なデザイン変更の場合は、デスクトップとモバイルの両方を確認してください。
スクリプット(Bashで実行。MCPはありません)
browser_* / Playwright MCPツールを探さないでください — インストールされていません。すべてはプレーンなNodeスクリプトで実行されます。このインストールされたSKILL.mdを含む絶対ディレクトリを解決し、VISUAL_VERIFY_DIRをそのディレクトリに設定します。これはプロジェクトインストールまたはグローバルインストールのいずれかです。あなたが読んでいる指示のコピーを使用し、ハードコードされたグローバルパスは使用しないでください。ワーキングディレクトリはアプリのプロジェクトルートに保ちます。この変数を各シェルコマンドで再利用してください(シェル状態が保持されない場合は再度設定してください):
VISUAL_VERIFY_DIR="/absolute/path/to/installed/visual-verify"
バンドルされているスクリプトは次のとおりです:
"$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" # URLをキャプチャしてpngに
"$VISUAL_VERIFY_DIR/scripts/composite.mjs" # 2つのpngからラベル付きbefore/afterを作成
"$VISUAL_VERIFY_DIR/scripts/touch.mjs" # 電話タッチ: タップ、ドラッグ、ターゲット監査
ランタイムとブラウザのセットアップ。 このスキルは正確なPlaywright依存関係とロックファイルを所有しています。グローバルまたはプロジェクトのPlaywrightパッケージを解決することはありません。スキルのインストールまたは更新後、明示的にインストーラーを実行してください。通常のチェックでは、パッケージ、イメージ、ブラウザをダウンロードしません。Node.js 20+、npm、Bashを使用してください。このスキルのためにホストシステムパッケージをインストールしないでください。
ブラウザの実行場所。 Dockerが利用可能な場合、起動のたびに、正確に一致し、すでにインストールされているPlaywrightイメージから独自のコンテナを作成します。Dockerは一意のループバックポートを割り当てます。ヘルパーはコンテナのIDを検証し、そのエンドポイントに接続します。スキルのインストールされたNode依存関係は読み取り専用でマウントされるため、サーバーはパッケージのダウンロードを必要としません。Playwrightはループバックリクエストをクライアントに転送するため、ホストネットワーキングなしでローカルアプリのURLにアクセスできます。通常の終了、起動失敗、ハンドリングされた終了では、そのラン固有のコンテナのみがクリーンアップされます。強制終了やホストクラッシュにより、ラベル付きコンテナが残る場合があります。明示的なクリーンアップの前に所有権を確認してください。既存のコンテナは置き換えられたり停止されたりしません。Docker Desktop/macOS ネットワーキングは依然として個別の検証が必要です。Linuxチェックからそれを主張しないでください。
Dockerがない場合、ヘルパーはインストールされたローカルブラウザのバイナリを使用します。VISUAL_VERIFY_DOCKER=0を設定してローカルモードを強制します。起動APIは明示的なバックエンドも受け入れます。JSON出力は実際のバックエンドとバージョンを報告します。
プロジェクトスクリプット用のサポートされている起動ツール
// このインポートを、インストール済みスキルディレクトリからの相対パスで解決してください。
const { launchBrowser } = await import("<インストール済みスキル>/scripts/load-playwright.mjs");
const { browser, where } = await launchBrowser("chromium", {
backend: "auto", // auto, docker, local
timeout: 30000,
launchOptions: { headless: true },
});
try {
// browser.newContext() などを使用。`where` を証拠とともに報告します。
} finally {
await browser.close();
}
launchOptionsは、ローカルのlaunchまたは固定されたDockerサーバーのブラウザ起動リクエストに渡されます。完全なPlaywrightサーバーにより、要求されたクライアントループバック転送が可能になります。Dockerはサーバーのホストとポートを所有します。ホスト固有の実行可能パスやその他のマシン固有のオプションは、呼び出し元の責任です。既存のloadChromium()およびloadBrowser(name)エクスポートは、ローカル限定の互換性APIとして残ります。これらはDockerを起動せず、不足しているブラウザを修復もしません。呼び出し元は、セットアップが動作を変更すると想定せず、意図的に移行してください。
Docker起動は、呼び出しごとに新しく一意の名前を持つサーバーコンテナを使用します。Dockerはループバックポートをアトミックに割り当てます。クライアントはコンテナのメタデータを検証し、報告されたWebSocketパスに接続します。Playwrightはクライアントのループバックトラフィックを転送し、ホストネットワーキングなしでローカル開発アプリへのアクセスを保持します。コンテナは、終了、起動失敗、ハンドリングされた終了時に削除されます。これにより、ウォームサーバーの再利用がエンドポイントの分離と引き換えになります。古い共有ポートのコンテナはそのまま残されます。強制終了やDockerの障害により、孤立したコンテナが残る可能性があります。doctor出力を検査し、明示的に削除する前に正確なコンテナの所有権を確認してください。一致するすべてのプロセス/コンテナを停止しないでください。クロスプラットフォームのDocker動作は、依然として独立した検証が必要です。
screenshot.mjs フラグ: --url --out [--width 390] [--height 844] [--dpr 2] [--mobile] [--wait 2000] [--click "Text or selector"] [--scroll-bottom "sel"] [--eval "js"] [--clip x,y,w,h] [--full]。--click は繰り返し可能で、まずボタンのアクセシブル名に一致し、次にCSSセレクターに一致します。タブ/メニュー/ダイアログの背後にある状態に到達するために使用します。
1回限りのインストール(マシンごと)
bash "$VISUAL_VERIFY_DIR/scripts/install.sh"
ロックされた依存関係をこのスキル自身の node_modules にインストールします。デフォルトの auto セットアップは、Dockerが利用可能な場合は一致するDockerイメージをプルし、それ以外の場合はローカルのChromiumをインストールします。インストーラーに docker または local を渡して明示的に選択します。ローカルのWebKitはこのコマンドではインストールされません。グローバルなnpmパッケージやシステムパッケージは変更されません。
ブラウザを起動したり、イメージをプルしたり、コンテナを変更したりせずに前提条件を検査します:
node "$VISUAL_VERIFY_DIR/scripts/doctor.mjs"
doctorは、スキル/ランタイムのバージョン、ランタイムパス、ローカル実行可能ファイルの存在、Dockerイメージの可用性、アクティブなVisual Verifyコンテナ/エンドポイント(レガシー名を含む)を報告します。終了ステータスは、選択されたデフォルトバックエンドのChromium前提条件をチェックします。ブラウザの起動やWebKitの可用性は証明しません。ファイルをインストールすることと、ブラウザを正常に起動することは別の証拠です。
以下で確認します:
node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
--url https://example.com --out /tmp/_vv_check.png --width 390 --height 844
画像とバックエンドのJSONを検査して、このスモークチェックが機能したことを確認します。
チェック対象の状態を待つ
スクリーンショットとタッチコマンドは、次のアクション後オプションをサポートしています:
--ready-selector "<selector>": 最初に一致する要素が表示されるのを待ちます。--ready-js "<expression>": ページの式(Promiseを含む)が真になるまでポーリングします。--ready-timeout 10000: 正の準備完了タイムアウト(ミリ秒単位)。セレクターと述語の待機で共有されます。また、--evalと--reportの評価を個別に制限します。--settle 0: 準備完了後のアニメーションのためのオプションの非負の遅延。
これらの条件は、すべてのクリック/タップ、スクロール、評価、ドラッグの後、監査とキャプチャの前に実行されます。両方の条件が指定された場合、両方を満たす必要があります。失敗した場合はゼロ以外で終了し、新しい成功スクリーンショットを書き込みません(既存の出力ファイルは削除されません)。一意の出力パスを選択してください。--wait はレガシーなアクション前の遅延を保持します。固定されたクリック/ドラッグ遅延は互換性のためのセトルとして残りますが、準備完了の証拠にはなりません。選択した条件が何を証明するかを述べてください。
node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
--url "<local-app-url>" --out visual-checks/search-desktop.png \
--click "Search" --ready-selector "[data-search-results]" \
--ready-js "document.querySelectorAll('[data-result]').length > 0"
ページ上にすでにある古い要素ではなく、期待される新しい状態に固有の条件を使用してください。非同期の結果を必要とする中間ステップの場合は、起動APIとPlaywrightロケーターをアクション間のアサーションとともに使用します。応答を待つ場合は、リクエストをトリガーする前に待機を登録し、その後レンダリングされた状態をアサートします。応答だけではレンダリングを証明しません。デバウンスされたアプリの場合、任意の遅延やnetwork-idleを完了の保証として扱わないでください。
出力場所
生成された画像は、リポジトリルートのgitignoreされた visual-checks/ に書き込みます(mkdir -p visual-checks)。リポジトリ内にいない場合、またはファイルを追加したくない場合は、代わりに一時ディレクトリを使用してください。ファイルをユーザーに送信する際は、安定したパスを参照してください。
1回の実行からのすべての画像に、表示内容を説明する共通の <change> プレフィックスを付けます(例: import-export-tab, header-nav) — 汎用的な before.png/after.png は使用しないでください。これにより、ディレクトリを見ればファイルがどの実行に属するか一目でわかります:
visual-checks/<change>-<viewport>.png # verifyモード: 1枚のショット
visual-checks/<change>-<viewport>-before.png # before/afterモード
visual-checks/<change>-<viewport>-after.png
visual-checks/<change>-<viewport>-before-after.png # 比較画像
ここで <viewport> は mobile または desktop です。
ワークフロー — Verifyモード
- アプリが実行中であり、そのURLを確認します(このプロジェクトの実行方法で起動します — 下記「アプリの実行」を参照)。
mkdir -p visual-checks。 - チェックする状態をキャプチャします。必要に応じて
--click/--eval/--scroll-bottomを使用してその状態に到達します:必要に応じて複数の幅をスイープするか、node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \ --url "<running app url>" --out visual-checks/<change>-mobile.png \ --width 440 --height 800 --mobile --wait 2000--mobileを外してデスクトップ用に--width 1280 --height 800などを使用します。 - 各画像を読み取り、正しいかどうかを明確に報告します。修正を確認する場合は、壊れていたものが実際に消えたことを確認します。機能を確認する場合は、実際にレンダリングされていることを確認します。
- 関連するショットを返信に表示します — 機能ごとに1つ(「確認した内容を表示する」を参照)。
ワークフロー — Before/afterモード
- スコープとビューポートを確認します。
mkdir -p visual-checks。共通の<change>プレフィックスを選択します。 - AFTERをキャプチャ — ワーキングツリーにはすでに変更が含まれています:
デスクトップの場合は、node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \ --url "<running app url>" --out visual-checks/<change>-mobile-after.png \ --width 440 --height 800 --mobile --wait 2000--mobileを外し、例:--width 1280 --height 800を使用し、接尾辞は-desktop-after.pngにします。 - BEFOREをキャプチャ — 視覚的な変更のみを一時的に元に戻し、
<change>-<viewport>-before.pngにスクリーンショットを撮り、その後元に戻します。復元を忘れるリスクを避けるため、gitを使用することを推奨します:- 未コミットの変更:
git stash push -- <file>→ スクリーンショット →git stash pop - コミット済みの変更:
git show HEAD~1:<path> > <path>(またはgit checkout <parent> -- <file>)→ スクリーンショット →git checkout -- <file>トグルとショットの間に開発サーバーがホットリロードするのを待ちます(--wait)。
- 未コミットの変更:
- 比較画像を作成 — 同じプレフィックス、接尾辞は
-before-after.png:node "$VISUAL_VERIFY_DIR/scripts/composite.mjs" \ --before visual-checks/<change>-mobile-before.png --after visual-checks/<change>-mobile-after.png \ --out visual-checks/<change>-mobile-before-after.png \ --title "Header at 440px (iPhone width)" \ --before-label "BEFORE — title squished" \ --after-label "AFTER — title full width" - 比較画像を読み取り、自分が主張する内容が示されていることを確認し、返信に表示します。
- BEFOREのトグルを元に戻します。 一時的なBEFOREの変更が適用されたままの状態でコミットしたりデプロイしたりしないでください — 終了前に必ず
git status/git diffを再確認してください。
モバイルタッチチェック
(…
[翻訳のため一部省略]
