フロントエンドテスト・デバッグは何をしますか？

呼び出し契約

このスキルは通常のユーザープロンプトから動作する必要があります。ユーザーにブラウザルーティング、スクリーンショット、レポート形式、フォールバックポリシーを明示的に要求させないでください。

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

この完全なワークフローをトリガーする例:

ウェブダッシュボードのトランザクション検索領域を改善してください。Web開発プラグインを使用してください
フロントエンド開発プラグインを使ってこのダッシュボードを磨いてください
Build Web Appsプラグインを使ってこのUIをデバッグしてください
このlocalhostアプリをテストし、壊れたインタラクションを修正してください

簡潔なプロンプトから、リポジトリ、現在開いているアプリ/ブラウザURL、近くのファイル、または実行中の開発サーバーを基に対象の画面を推測してください。ターゲットURLが不明な場合は、ユーザーに尋ねる前にリポジトリのスクリプトと実行中のローカルポートを検査してください。

レンダリングされたフロントエンド画面に対するコード変更については、デフォルトで以下の検証ループを実行してください:

対象フローを特定する。
以下のブラウザパスを選択する。
最小限の有用な編集を行う。
レンダリングされた動作を検証する。
QA最終応答レポートで応答する。

ブラウザパスの選択

最初にブラウザの利用可能性を分類:

利用可能: Browserプラグインとそのbrowserスキルがセッションにリストされている。ブラウザ操作の前にそのスキルを読み、従うこと。
不在: Browserプラグインまたはbrowserスキルがリストされていない。通常のPlaywrightを使用し、Browser plugin not availableを記録する。
呼び出し失敗: Browserは利用可能に見えるが、スキル/ランタイム、Node REPL JavaScriptセットアップ、タブ取得、またはナビゲーションが失敗する。これをBrowserパスブロッカーとして扱う。

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

失敗したBrowser呼び出しから通常のPlaywrightへの切り替えは、ユーザーがすでにフォールバックを許可している場合、またはタスクが明示的に非ブラウザ検証を許可している場合のみ行ってください。その場合、正確なBrowserの失敗とフォールバックの決定を報告してください。

対象フロー

ブラウザ検証の前に、対象フローを一文で定義してください:

テスト対象フロー: [エントリールート] -> [ユーザーアクションまたは状態] -> [期待されるレンダリング結果]。

ユーザーが一般的なスモークテストを要求した場合は、以下を使用してください:

テスト対象フロー: アプリ読み込み -> 最初の意味のある画面がレンダリングされる -> 主要な可視コントロールがランタイムエラーなく応答する。

ブラウザプラグインループ

Browserスキルで説明されているNode REPL JavaScriptツールを使用してBrowserコマンドを実行してください。別のブラウザセットアップパスを考案しないでください。Browserスキルが別の指示をしない限り、同じタブバインディングを使用し続けてください。

必要なシーケンス:

Browserスキルの指示に正確に従ってBrowserランタイムをロードする。
セッションにagent.browser.nameSession("...")で名前を付ける。
agent.browser.tabs.selected() または agent.browser.tabs.new() でタブを取得する。
tab.goto(url) でナビゲートする。
以下の必要なチェックを実行する。
スコープ付きの tab.playwright ロケーターまたはBrowserスキルのインタラクションAPIを使用して操作する。
編集後、await tab.reload() を呼び出し、チェックと失敗したインタラクションを繰り返す。

UIを変更するアクションごとに、次の状態が正しいことを示す最も軽量な証拠を収集してください: 新しいDOMスナップショット、可視テキスト/状態、URL変更、フォーカスされたコントロール、トースト、モーダル、スクリーンショット、またはコンソールログ。

必須のブラウザチェック

レンダリングされたアプリが動作すると主張する前に、以下のチェックを実行してください:

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

ビジュアル作業の場合は、可能な場合はデスクトップに加えて1つのモバイルサイズのビューポートを追加してください。リファレンス駆動型の作業の場合は、短い不一致台帳を保持してください: リファレンス証拠、レンダリング証拠、修正または意図的な逸脱。

Playwrightループ

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

以下の順序を使用してください:

package.json でスクリプトを見つける。
リポジトリのパッケージマネージャーでアプリを起動し、要求されたホストを正確に維持する。
リポジトリのe2eスクリプトが存在する場合はそれを優先する。
そうでない場合、Playwrightが設定されているときは pnpm exec playwright test またはパッケージマネージャーと同等のコマンドを実行する。
プロジェクトにPlaywrightワークフローがない場合、pnpm exec playwright --version でPlaywrightを確認し、pnpm exec playwright screenshot <url> /tmp/frontend-check.png でスクリーンショットをキャプチャする。
より詳細なデバッグのために、コミットされたソース外に小さな一時的なPlaywrightスクリプトを作成し、URLを開き、コンソールエラー、スクリーンショットをキャプチャし、対象のインタラクションを実行する。
編集後、同じコマンドまたはスクリプトを再実行する。

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

検証チェックリスト

要求されたホストを正確に維持する。
コントロールが実際のUI状態を更新することを確認する。
スクロール前の最初のビューポートと、可能な場合はデスクトップおよび1つのモバイルサイズのビューポートを確認する。
クリッピング、オーバーラップ、読めないテキスト、折り返し、レイアウトシフト、アセット欠落、z-index問題、スクロールトラップ、スタローディング、壊れた状態を探す。
リファレンス駆動型の作業の場合は、レンダリングされたスクリーンショットをリファレンスと比較し、短い不一致台帳を保持する。
レンダリングされた検証が要求された場合、ビルドの成功だけでは不十分です。

QA最終応答レポート

重要なレンダリングUI検証実行の場合、QAエンジニアがコード変更を検証するかのように最終応答を作成してください。応答により、ユーザーまたはPRレビュアーが何が変更され、何がテストされ、何が証拠として示され、何が未テストかを簡単に理解できるようにする必要があります。

以下の形式を使用してください:

サマリー: ユーザーから見える変更とQAが合格したかどうかを説明する1～2の箇条書き。
環境: URL、ビューポート、Browser利用可能性分類、Playwrightが使用された場合はフォールバック理由。
検証済みの変更: 変更されたファイルまたは画面、および期待される具体的なユーザー向け動作。
チェック: ページ識別、空白ページチェック、フレームワークオーバーレイチェック、コンソールの健全性、スクリーンショット証拠、インタラクションの証明に関する合格/不合格テーブル。
インタラクションループ: テストされた正確なインタラクションパス。実行されたコントロールまたはワークフローと観察された状態変化を含む。
証拠: QAセクションでスクリーンショット証拠を説明し、実際のスクリーンショットを応答の最後に連続した画像として配置する。関連するBefore、After、インタラクション、レスポンシブ、エラー、または修正された状態を証明するのに有用な数のスクリーンショットを含める。
コマンド / Browser API: 使用された主要なコマンドとBrowser APIシーケンスを列挙する。ノイズの多いログはダンプしない。
残存リスク: 未テストのビューポート、フロー、ブラウザ、データ状態、または既知の制限。

問題が見つかった場合は、サマリーの前に所見を先頭に記載してください。各所見には、ユーザーが見るもの、再現手順、スクリーンショット/DOM/コンソール証拠、既知の場合は推定される所有者またはファイル、および行われた修正または残っているブロッカーを含める必要があります。

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

スクリーンショットをレポート全体に散りばめないでください。最後に短い スクリーンショット セクションを設け、連続した画像ギャラリーとし、1行に1画像としてください。状態を明確にする場合にのみ短いラベルを追加してください。例: Before、After、Filtered results、Empty state、Mobile。

デフォルトでは個別のHTMLレポートを作成しないでください。ユーザーが明示的に要求した場合のみスタンドアロンレポートファイルを作成し、ユーザーがコミットされた成果物を明示的に要求しない限り、リポジトリ外に書き込んでください。

ユーザーが明示的にコミットされた成果物を要求しない限り、レポート、スクリーンショット、トレース、一時スクリプトをリポジトリに書き込まないでください。

最終応答

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

Browserが不在でPlaywrightが使用された場合は、最後にユーザーに、アプリ内ナビゲーション、スクリーンショット、DOMスナップショット、コンソールログ、インタラクション検証を備えたより良いフロントエンド開発体験のためにBrowserプラグインのインストールを提案してください。

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