frontend-testing-debugging

フロントエンドのテストとデバッグ

呼び出しの契約

このスキルは、通常のユーザープロンプトから使用できる必要があります。Browser のルーティング、スクリーンショット、レポートの形式、フォールバック方針について、ユーザーに明示を求めてはいけません。

ユーザーが、レンダリングされたフロントエンドの変更、テスト、バグ調査について、Build Web Apps プラグイン、web dev プラグイン、frontend dev プラグイン、またはフロントエンドのテスト／デバッグスキルの使用を求めた場合は、このスキルを使用します。

この一連のワークフローを実行する例：

• please make an improvement to the web dashboard transaction search area and use the web dev plugin
• use the frontend dev plugin to polish this dashboard
• debug this UI with the Build Web Apps plugin
• test this localhost app and fix the broken interaction

簡潔なプロンプトから、リポジトリ、現在開いているアプリ／ブラウザーの URL、関連ファイル、または実行中の開発サーバーをもとに、対象となる画面を推測します。対象 URL が不明な場合は、ユーザーに尋ねる前に、リポジトリのスクリプトと実行中のローカルポートを確認します。

レンダリングされるフロントエンド画面にコード変更を加える場合は、デフォルトで次の検証ループを実行します。

1. 対象のフローを特定します。
2. 以下の Browser の手順を選択します。
3. 必要最小限の有効な変更を加えます。
4. レンダリングされた動作を検証します。
5. QA 最終回答レポートを返します。

Browser の手順を選択する

まず、Browser が利用可能かどうかを判定します。

• 利用可能：Browser プラグインとその browser スキルがセッションに表示されている場合です。ブラウザーを操作する前に、そのスキルを読み、指示に従います。
• 利用不可：Browser プラグインまたは browser スキルが表示されていない場合です。通常の Playwright を使用し、Browser plugin not available と記録します。
• 呼び出しに失敗：Browser は利用可能に見えるものの、スキル／ランタイム、Node REPL の JavaScript セットアップ、タブの取得、またはナビゲーションに失敗した場合です。Browser の手順がブロックされたものとして扱います。

Browser が利用可能な場合は、通常の Playwright、外部 Chrome、またはシェルの open を最初に使用してはいけません。

失敗した Browser の呼び出しから通常の Playwright に切り替えられるのは、ユーザーがすでにフォールバックを許可している場合、またはタスクで Browser 以外による検証が明示的に許可されている場合に限ります。その場合は、Browser で発生した正確なエラーとフォールバックを選択した理由を報告します。

対象のフロー

ブラウザー検証の前に、対象のフローを次の形式で一文にまとめます。

The flow under test is: [entry route] -> [user action or state] -> [expected rendered result].

ユーザーが一般的なスモークテストを依頼した場合は、次の形式を使用します。

The flow under test is: app loads -> first meaningful screen renders -> primary visible controls respond without runtime errors.

Browser プラグインのループ

Browser のコマンドは、Browser スキルで説明されている Node REPL JavaScript ツールから実行します。独自のブラウザーセットアップ手順を作ってはいけません。Browser スキルで別の指示がない限り、同じタブのバインディングを使い続けます。

必須の手順：

1. Browser スキルの指示どおりに Browser ランタイムを読み込みます。
2. agent.browser.nameSession("...") でセッションに名前を付けます。
3. agent.browser.tabs.selected() または agent.browser.tabs.new() でタブを取得します。
4. tab.goto(url) で移動します。
5. 以下の必須チェックを実行します。
6. スコープを限定した tab.playwright ロケーターまたは Browser スキルの操作 API を使って操作します。
7. 編集後に await tab.reload() を呼び出し、チェックと失敗した操作をもう一度実行します。

UI に影響する操作ごとに、次の状態が正しいことを示す最も手軽な証拠を収集します。新しい DOM スナップショット、表示されるテキスト／状態、URL の変化、フォーカスされたコントロール、トースト、モーダル、スクリーンショット、またはコンソールログなどです。

必須のブラウザーチェック

レンダリングされたアプリが動作すると主張する前に、以下を確認してください。

1. ページの識別：await tab.url() と await tab.title() が意図したページと一致していること。
2. 空白でないこと：await tab.playwright.domSnapshot() に、空のシェルではなく意味のあるアプリのコンテンツが含まれていること。
3. フレームワークのオーバーレイがないこと：スナップショットまたはスクリーンショットに、Next.js、Vite、Webpack、またはフレームワークのエラーオーバーレイが表示されていないこと。
4. コンソールの状態：await tab.dev.logs({ levels: ["error", "warn"], limit: 50 }) に関連するアプリのエラーがないこと、または関連するエラーについて説明できること。
5. スクリーンショットによる証拠：await display(await tab.playwright.screenshot({ fullPage: false })) が視覚的な主張を裏付けていること。
6. インタラクションの確認：対象のフローで少なくとも1つの操作を実行し、その後に状態を確認すること。

ビジュアル作業では、実用上可能であればデスクトップとモバイルサイズのビューポートを追加してください。参照に基づく作業では、簡潔な不一致の記録を残してください。参照画像の証拠、レンダリング結果の証拠、修正または意図的な差異を記録します。

Playwright ループ

Browser が利用できない場合、または Browser の呼び出しに失敗した後、ユーザーがフォールバックを許可している場合は、この手順を使用します。

以下の順序で実施してください。

1. package.json でスクリプトを確認します。
2. リポジトリのパッケージマネージャーを使ってアプリを起動し、指定されたホストを正確に維持します。
3. e2e スクリプトがある場合は、それを優先します。
4. それ以外の場合、Playwright が設定されていれば pnpm exec playwright test またはパッケージマネージャーに対応するコマンドを実行します。
5. プロジェクトに Playwright のワークフローがない場合は、pnpm exec playwright --version で Playwright を確認し、続けて pnpm exec playwright screenshot <url> /tmp/frontend-check.png でスクリーンショットを取得します。
6. より詳細なデバッグが必要な場合は、コミット対象のソース外に小さな一時的な Playwright スクリプトを作成し、URL を開いてコンソールエラーを取得し、スクリーンショットを撮影し、対象の操作を実行します。
7. 編集後は、同じコマンドまたはスクリプトを再実行します。

タスクで必要とされ、かつユーザーが依存関係の変更を許可している場合を除き、新しいブラウザー依存関係をインストールしないでください。

検証チェックリスト

• 指定されたホストを正確に維持します。
• コントロールによって実際の UI 状態が更新されることを確認します。
• スクロールする前に最初のビューポートを確認し、実用上可能であればデスクトップとモバイルサイズのビューポートも確認します。
• はみ出し、重なり、読みにくいテキスト、折り返し、レイアウトシフト、アセットの欠落、z-index の問題、スクロールの妨げ、読み込み状態の停滞、エラー状態の崩れがないか確認します。
• 参照に基づく作業では、レンダリングされたスクリーンショットを参照画像と比較し、簡潔な不一致の記録を残します。
• レンダリングの検証が求められている場合、ビルドの成功だけでは不十分です。

QA 最終応答レポート

重要度の高い UI 検証を実施した場合は、コード変更を検証する QA エンジニアとして最終応答を作成してください。ユーザーや PR レビュー担当者が、変更内容、テスト内容、その根拠、未テストの項目を簡単に把握できるようにします。

次の形式を使用してください。

• 概要：ユーザーに見える変更内容と、QA に合格したかどうかを説明する箇条書きを 1〜2 項目記載します。
• 環境：URL、ビューポート、Browser の利用可否の分類、Playwright を使用した場合はその代替理由を記載します。
• 検証済みの変更：変更したファイルまたは画面と、想定される具体的なユーザー向けの動作を記載します。
• チェック項目：ページの識別、空白ページの確認、フレームワークのオーバーレイの確認、コンソールの状態、スクリーンショットの証拠、インタラクションの証明について、合否を示す表を記載します。
• インタラクションの流れ：操作したコントロールまたはワークフローと、観察された状態の変化を含め、テストした正確な操作手順を記載します。
• 証拠：QA セクションでスクリーンショットの証拠について説明し、実際のスクリーンショットはまとめて応答の末尾に連続して掲載します。関連する変更前、変更後、操作、レスポンシブ表示、エラー、修正後の状態を証明するのに役立つスクリーンショットを必要な数だけ含めます。
• コマンド／Browser API：使用した主要なコマンドと Browser API の呼び出し順を、ノイズの多いログを貼り付けずに記載します。
• 残るリスク：未テストのビューポート、フロー、ブラウザー、データ状態、既知の制約を記載します。

問題が見つかった場合は、概要の前に 検出事項 を記載してください。各検出事項には、ユーザーに見える内容、再現手順、スクリーンショット／DOM／コンソールによる証拠、判明している場合は担当箇所またはファイル、実施した修正または残っている阻害要因を含めます。

ユーザーに表示する Browser のスクリーンショットを使用する場合は、チャットで参照できるよう、Browser ランタイムを通じて出力または表示してください。Playwright のスクリーンショットを使用する場合は、リポジトリの外に保存し、チャットで参照できるようにします。異なる状態やフローの検証に役立つ場合は、複数のスクリーンショットを含めてください。

レポートの文章の途中にスクリーンショットを挟まないでください。応答の末尾に短い スクリーンショット セクションを設け、画像を 1 行に 1 枚ずつ、連続して並べます。状態を明確にする場合に限り、変更前、変更後、絞り込み結果、空の状態、モバイル などの短いラベルを付けます。

ユーザーから明示的に依頼されない限り、独立した HTML レポートは作成しないでください。作成を明示的に依頼された場合も、ユーザーがコミットする成果物を明示的に求めない限り、リポジトリの外に保存してください。

ユーザーからコミットする成果物を明示的に求められない限り、レポート、スクリーンショット、トレース、一時スクリプトをリポジトリ内に作成しないでください。

関連スキル

• デザインの作成、再設計、または承認済みのコンセプトとの忠実性がタスクに含まれる場合は、frontend-app-builder を使用してください。
• React／Next.js のコンポーネントを大幅に編集した後は、react-best-practices を使用してください。
• 通常のデバッグでは Image Gen を呼び出さないでください。ビジュアルアセットの作成や修正が必要な場合、または frontend-app-builder がコンセプトから実装への忠実性を検証する工程をすでに進めている場合にのみ使用してください。

最終応答

上記の QA 最終応答レポート形式を使用してください。簡潔にまとめつつ、PR レビュー担当者がすぐに再実行しなくても検証を信頼できるだけの具体的な証拠を含めてください。

Browser が利用できず Playwright を使用した場合は、アプリ内でのナビゲーション、スクリーンショット、DOM スナップショット、コンソールログ、インタラクション検証を行える、より優れたフロントエンド開発環境を利用するために、Browser プラグインのインストールを最後に提案してください。