browser-qa

ブラウザー QA

実際のブラウザーを操作して、機能を検証しようとしています。Playwright MCP を使用してください。 実用面で価値があるブラウザースタックはこれだけです。高速で、スクリプトから操作でき、スナップショットに対応しています。また、エラーはプロンプト層で発生するため、ランタイムを再起動せずに、より適切な再試行で復旧できます。

初回セットアップ — 何よりも先に実行してください

許可が必要になってから申請しようとすると、タスクの途中で作業が止まってしまいます。QA フェーズの最初のメッセージで、不足しているものがあればすべて伝えてください。

1. mcp__playwright__browser_close を一度呼び出して、Playwright MCP が動作することを確認します。開いているタブがなければ何もせず、早い段階で「browser already in use」というロックエラーがあれば通知されるため、タスクの途中で問題になる前に pkill -f "mcp-chrome-" を実行できます。
2. 開発サーバーが起動していることを確認します。curl -s -o /dev/null -w "%{http_code}\n" http://localhost:<port>/ をすばやく実行すれば、「Page Title: ECONNREFUSED」という往復を避けられます。

不足しているものがあれば、すぐに伝えてください。状況が不確かなまま QA を始めないでください。

なぜ Playwright なのか？ 高速で、スクリプトから操作でき、スナップショットに対応しています。また、エラーはプロンプト層で発生するため、ランタイムを再起動せずに、より適切な再試行で復旧できます。ヘッドレスのスクリーンショットは情報量が多く、淡々としており、まさにレビュアーが求めているものです。スタックは一つに絞り、その鋭いクセを把握しましょう。

Playwright MCP の失敗パターン — すべて自分で解決できます

• 前回のセッションからブラウザーのロックが残っている。 pkill -f "mcp-chrome-" を実行してから再試行してください。
• URL パスを推測して 404 になる。 ページに移動する前に、プロジェクトのルーティング設定（Next.js の pages/／app/、Vite の routes.tsx、React Router、ファイルベースのルーターなど）を確認してください。機能名から URL のパターンを決めつけないでください。
• browser_take_screenshot で「許可されたルートの外です」というエラーが発生する。 スクリーンショットツールはサンドボックス内（通常は <cwd> と <cwd>/.playwright-mcp）にしか書き込めません。~/Projects/pr-screenshots や /tmp に直接保存することはできません。単純なファイル名（例：drawer-light.png）を渡すと、ファイルはワークツリーのルートに保存されます。その後、そこから pr-screenshots のクローンにコピーしてください。スクリーンショットがどこに保存されたかを探して時間を無駄にしないでください。ファイルは <cwd> にあります（スラッシュを含む相対パスを使った場合は、その .playwright-mcp サブディレクトリ内にあります）。
• wait_for でポータルを使うコンポーネント（Radix、Headless UI、Chakra v3、MUI Modal）のテキストを待つ場合、条件が不十分になる。 開く操作を行ったトリガーではなく、ポータル内のコンテンツ（フィールドのラベルやダイアログ内の見出しなど）を待ってください。
• evaluate で表示テキストをクリックしても、適切なハンドラーが呼び出されないことが多い。 多くのコンポーネントライブラリ（Chakra、Radix、shadcn/ui、MUI）では、クリックハンドラーはユーザーに見えている行やリスト項目ではなく、<button> やアイコンのトリガーなど、内側の要素に設定されています。DOM を上下にたどって、実際に操作できる要素（通常は <button> または [role="button"]）を見つけてクリックしてください。
• evaluate で設定した Cookie が、ページ遷移後に失われることがある。 アプリが未認証のリクエストをリダイレクトする場合は、まず静的アセットや JSON API ルートなど、リダイレクトされず 200 を返すエンドポイントに移動し、そこで Cookie を設定してから目的のページに移動してください。
• カラー モード（テーマ）の切り替えは、localStorage に書き込んでクラスを切り替えるだけではできない。 テーマプロバイダー（next-themes、Chakra の ColorModeProvider など）は、マウント時に React を通じて状態を読み取ります。ページのハイドレーション後に DOM を直接切り替えても、レンダリング済みのツリーには反映されません。次のいずれかを行ってください。
  • browser_click でテーマ切り替えボタンをクリックする（最も確実です）。
  • ページに移動する前にストレージキーを設定してから再読み込みし、マウント時にプロバイダーがストレージから状態を再読み込みするようにする。 実際にモードが切り替わったと決めつける前に、スクリーンショットを撮って確認してください。
• トグルの上にモーダル／ドロワーがある。 ドロワー／ダイアログが開いた状態でブラウザーのコントロールをクリックしようとすると、ダイアログの背景がクリックを遮ります。グローバル UI を操作する前に、ダイアログを閉じてください（Esc、X、またはストアレベルの close 呼び出し）。
• ファイルシステムをポーリングしてスクリーンショットのパスを探さないでください。 Playwright の応答で path: './<filename>.png' と確認できます。それが正しいパスです。ファイルが見つからない場合は、想定している場所と作業ディレクトリが異なります（pwd を一度実行してください。検索は不要です）。

パフォーマンスの目安

実際の「設定 → ドロワーを開く → スクリーンショットを撮る」という QA フローの場合：

スタック	順調な場合	観測された最悪値	失敗パターン
Playwright	約 12 秒	約 60 秒（デバッグ時）	プロンプト層、再試行可能

スクリーンショットを 1 枚撮るフローでは、ツール呼び出しの回数は通常 8～9 回です。複数の状態（ライト＋ダーク、狭い＋広い）のキャプチャはまとめて行えます。ビューポートを切り替え、スクリーンショットを撮り、繰り返してください。

QA フローそのもの

1. 他のエージェントやハードコードされた認証コールバックと競合しない開発サーバーのポートを選びます。 プロジェクトで外部の認証プロバイダー（Auth0、Clerk、OAuth を使う NextAuth、Supabase、Cognito など）を使用している場合は、コールバックの許可リストにすでに含まれているポートを選びます。任意のポートを設定すると、リダイレクトが通知なく失敗します。それ以外の場合は、ほかのユーザーが実行しているものと競合しないよう、目立たないポート（例：4 桁の大きな番号）を選びます。
2. テストデータは UI ではなくスクリプトで投入します。 必要な行（ユーザー、セッショントークン、サンプルレコードなど）を、プロジェクトの DB クライアント、ORM、またはシード機能を使って直接作成する小さなセットアップスクリプトを記述します。オンボーディング画面をクリックして進めるより速く、実行のたびに再現でき、タスクの途中でセッションの有効期限が切れても問題ありません。
3. wait_for で実際のコンテンツを待ってから移動し、クリックし、wait_for で次のコンテンツを待って、スクリーンショットを撮ります。常に document.readyState だけでなく、ユーザーが実際に目にするコンテンツを待ちます。
4. レビュー担当者が確認したいタイミングでスクリーンショットを撮ります ――初期状態、フローの途中、最終状態です。UI を刷新する場合は、両方のカラーモード（ライトとダーク）と両方のレイアウトブレークポイント（例：狭い幅と広い幅）を撮影します。通常は 3～6 枚で十分です。10 枚では多すぎます。
5. 機能を検証してから、想定外の経路も検証します。 「正常系が動作する」だけでなく、「明らかなエラーケースで明確なメッセージが表示される」こと、さらに「フォームのバリデーションで不正な入力が拒否される」ことも確認します。バグはほとんどの場合、QA しなかった経路にあります。
6. ブラウザーのスクリーンショットで動作を確認するまでは、機能が動作すると断言してはいけません。 テストの成功は必要条件ですが、十分条件ではありません。

スクリーンショットの取り扱い ――必須

スクリーンショットは省略できません。 すべての QA セッションで、PR にアップロードするスクリーンショットを用意する必要があります。スクリーンショットが埋め込まれていないのに「準備完了」と報告された PR は未完成です。戻って撮影してください。後回しにせず、QA の最中に実施します。

• ユーザー向けドキュメントの素材として明示的に使う場合を除き、作業リポジトリにスクリーンショットをコミットしてはいけません。 .claude/、bench/、またはほかの Git の追跡対象外の場所に保存します。（誤って git add -A を実行してスクリーンショットがコミットに含まれた場合は、プッシュする前にコミットを修正して取り除きます。）
• langwatch/pr-screenshots 経由で公開します（~/Projects/pr-screenshots にクローン済み）：

  cd ~/Projects/pr-screenshots && git pull --rebase
  cp /path/to/shot.png pr-<PR#>/<section>/<name>.png
  git add . && git commit -m "pr-<PR#>: <what>" && git push origin main
  

  生 URL は https://raw.githubusercontent.com/langwatch/pr-screenshots/main/pr-<PR#>/<section>/<name>.png です。
• PR を準備完了として報告する前に、生 URL を PR の説明文に埋め込みます。コミットしたファイルでも、コメントでもなく、PR 本文に記載します。

QA フェーズの終了

次のすべてに「はい」と答えられたら、ブラウザー QA は完了です。

• コードパスが実行されることを証明する画面に移動しただけではなく、ユーザーと同じように機能を操作しました。
• 想定外の経路（設定の欠落、不正な入力、関連する場合はネットワーク障害のシミュレーション）を試しました。
• 正常系と、最も重要なエッジケースのスクリーンショットがあります。
• UI の作業では、両方のカラーモードと（レイアウトが変化する場合は）両方のブレークポイントのスクリーンショットがあります。
• スクリーンショットは langwatch/pr-screenshots にプッシュされ、PR 本文に埋め込まれています（ローカルで撮影しただけではなく、現時点で実際に PR の説明文に記載されています）。
• QA 中に少なくとも 1 つ、UX 上の粗を見つけ、それを修正するか、課題として登録しました。

すべてに「はい」と答えられない場合、QA はまだ完了していません。スモークテストをしただけです。戻って機能を使ってください。

必須ゲート： PR にスクリーンショットがない状態で「CI はすべて成功、PR の準備完了」と報告してはいけません。まずスクリーンショットを用意し、その後に状況を報告します。