mcpField
F
frontend-visualqa

frontend-visualqa

github.com/yutori-aiテスト・品質1058 回インストール4 週間前に更新
リポジトリ

frontend-visualqa について

コード変更後に、スクリーンショットを根拠としてフロントエンドの描画を確認するスキルです。指定ルートや表示状態、レスポンシブ動作を検証するエージェント向けで、MCP ツールがない場合はコマンドラインに切り替えられます。

主な機能

  1. 01スクリーンショットで視覚的な主張を検証
  2. 02切れ、はみ出し、表示、レスポンシブ動作を確認
  3. 03メニューやモーダルなどの操作状態をテスト
  4. 04認証フロー向けの永続ブラウザーセッションに対応
  5. 05MCP ツールがない場合のコマンドライン手段

活用シーン

  1. 01ページが想定したルートや表示状態か確認
  2. 02変更後のレイアウトの切れやテキスト省略を確認
  3. 03メニュー、タブ、通知、無効ボタンを検証
  4. 04ビジュアル QA レポート用の証拠を撮影

MCP 対応

verify_visual_claims、take_screenshot、manage_browser などの frontend-visualqa MCP ツールを優先します。MCP サーバーを利用できない場合のコマンドライン手段も記載されています。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/yutori-ai/frontend-visualqa --skill frontend-visualqa

インストール後、Claude Code で/frontend-visualqaを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

agents/
openai.yaml
references/
claim-writing.md
install.md
protocol.md

詳細

フロントエンドのビジュアル QA

UI コードを変更した後、DOM のアサーションだけでは不十分で、ページが実際にどのように描画されたかをスクリーンショットで証明する必要がある場合に、このスキルを使用します。

次の用途で使用します。

  • エージェントが正しいルートまたは UI の状態にいることを確認する
  • 表示状態、クリッピング、オーバーフロー、z-index、テキストの省略、レスポンシブ動作を確認する
  • モーダル、メニュー、トースト、タブ、無効化されたボタンなどのインタラクティブな状態を検証する

次の用途には使用しないでください。

  • 開発サーバーを起動する
  • 「見栄えをよくして」のような曖昧な依頼に対応する
  • アプリ全体の広範囲にわたるビジュアル差分を確認する

クイックスタート

  1. フロントエンドがすでにローカルで実行されていることを確認します。
  2. 利用可能な場合は、frontend-visualqa MCP ツールを優先してください。呼び出し間でブラウザーの状態を維持できます。
  3. ページへのアクセスに認証が必要で、ユーザーが対応できる場合は、action="login" とログイン URL を指定して manage_browser を呼び出します。ユーザーが認証できるよう、永続的なヘッド付きブラウザーが開きます。その後は同じ session_key を再利用し、認証済みセッションを使い終えたら manage_browser(action="close", ...) を呼び出します。
  4. ユーザーが URL と明示的な主張を提示した場合は、直接 verify_visual_claims を呼び出します。内部でスクリーンショットを取得するため、別途 take_screenshot を呼び出す必要はありません。
  5. まだ主張がなく、記述する前にページを確認する必要がある場合に限り、先に take_screenshot を呼び出します。
  6. フロントエンドを修正し、同じ主張が通るまで再実行します。

主張の作成ルール

主張はピクセルから観察できる内容にしてください。例と避けるべきパターンについては、references/claim-writing.md を開いてください。

主張が真偽を確認する前に操作を必要とする場合は、navigation_hint を指定してください。主張文の中に複数ステップのスクリプトを埋め込まず、最終的に表示される状態に焦点を当ててください。

一部の主張だけにセットアップが必要な複数主張のフローでは、主張ファイルを使用し、次の例のように、該当する箇条書きの下に主張ごとのメタデータを記述してください。

- After logging in, the dashboard shows "Welcome back, Developer"
  - navigation_hint: Type "[email protected]" in the email field, type "password123" in the password field, then click Continue.
- The API Calls Today stat card shows the value 1,247

MCP を使用する場合、セットアップが主張ごとに異なるウォームセッションの検証は、verify_visual_claims を連続して呼び出して分けてください。1 回のバッチ内で、グローバルなナビゲーションヒントが選択的に適用されることは期待しないでください。

セッション戦略

公開ページや簡単な確認には、エフェメラルモードを使用します。

認証が必要なアプリ、複数ステップのフロー、または実行をまたいで Cookie とローカルストレージを保持する必要がある場合は、永続モードを使用します。MCP 主導のワークフローでは、主張を実行する前に manage_browser(action="login", ...) で認証をセットアップします。

セットアップとクライアント固有のインストールコマンドは、references/install.md に記載されています。 詳細な QA プレイブック、ステータスの意味、復旧手順は、references/protocol.md に記載されています。

ユーザーへの証拠の提示

すべてのツール応答には、スクリーンショット証拠のファイルパスが含まれます。この証拠は必ず提示してください。テキストの結果を要約するだけにしないでください。

verify_visual_claims は artifacts_dir と、各主張について results[].proof.screenshot_path（決定的なスクリーンショット）および results[].proof.text（テキストによる要約）を返します。途中のステップで撮影された追加のスクリーンショットは、results[].trace.screenshot_paths にあります。

take_screenshot は screenshot_path を返します。

検証の実行後は、次の手順に従ってください。

  1. 失敗した主張や結論が出なかった主張については、証拠となるスクリーンショットファイルを読み、視覚的に何が問題かを説明できるようにします。
  2. スクリーンショットのパスをユーザーに示し、クライアントが対応している場合は、画像をインラインで開くか表示します。
  3. 結果を要約する際は、テキストの判定を繰り返すだけにせず、具体的な視覚的証拠を示します。

クライアントが画像のインライン表示に対応していない場合は、ユーザーが手動で開けるよう、絶対パスを出力してください。

ツールの優先順位

次の順でツールを優先してください。

  • ユーザーが主張を提示している場合は verify_visual_claims。これは主なツールであり、独自にスクリーンショットを取得します。
  • 主張を記述する前にページを確認する必要がある場合に限り、take_screenshot
  • 共有ブラウザーの状態が古い、サイズが不適切、またはリセットが必要な場合は manage_browser

MCP サーバーを利用できない場合は、references/install.md にある CLI の代替手段を使用してください。

$ARGUMENTS

コメント

Markdown 対応