Playwright E2E with playwright-e2e-mcp
このスキルは playwright-e2e-mcp MCP サーバーを駆動します。サーバーはあなたの代わりに Playwright を実行し、生のターミナル出力ではなく構造化された結果（パス/失敗の統計、各失敗の file:line、失敗の種類、失敗時の DOM（Playwright トレースから読み取り）、失敗したネットワークリクエスト、コンソールエラー、具体的な次のステップ）を返します。また、壊れたロケーターの検証済み修正を提案して適用したり、ログイン後のページを調査したり、長時間のスイートをバックグラウンドで実行したり、すべての実行のローカル履歴を保持したりすることもできます。
このスキルは playwright-e2e-mcp 0.16.0 用に書かれており、0.2.0 以降で動作します。suggest-fix、get-run-status、analyze-history がない場合、サーバーは 0.2.0 より古いものです。それらのツールを必要としない手順を使用し、ユーザーに更新を促してください。diagnose-flaky のテストごとのテーブルと isolate オプションは 0.3.0 で追加されました。audit-accessibility、diagnose-flaky の order オプション、run-test の根本原因グループ化は 0.4.0 で追加されました。audit-performance、load-report、ネットワークモック（routes）、har、browser、inspect-page の view: "aria"、generate-e2e-test の steps、履歴ビューの slow、trend、commits、suggest-fix の strict-mode 修正は 0.5.0 で追加されました。save-login、check-test-change、quarantine は 0.7.0 で追加されました。switchTab ページステップ、blockWrites、クラッシュした実行のリカバリ、pytest-playwright プロジェクト（run-test、get-failure、list-tests）は 0.8.0 で追加されました。無料のセルフホスト履歴サーバー（PW_MCP_HISTORY_URL / PW_MCP_HISTORY_TOKEN、古い Pro 設定を置き換えますが、まだ動作します）は 0.9.0 で追加されました。ファイルを変更する前の確認、インタラクティブテストレポート（MCP Apps）、Client ID Metadata Documents によるサインインは 0.10.0 で追加されました。コンパクトな inspect-page ロケーターマップ（デフォルトビュー）と load-tools（--tools=auto）は 0.11.0 で追加されました。check-mocks、inspect-page、get-failure、diagnose-flaky のハイドレーションノート、check-test-change の runtime オプションと pytest サポートは 0.12.0 で追加されました。CI 実行 URL を使用した load-report、connect、suggest-fix の Python 修正は 0.13.0 で追加されました。run-test の changed、suggest-fix の verifyAllProjects、ビジュアル mask、blockResources、offline は 0.14.0 で追加されました。diagnose-flaky、audit-tests、generate-e2e-test の pytest サポートは 0.15.0 で追加されました。複数のブラウザをテストするプロジェクトで修正を検証する場合は、verifyAllProjects: true を渡してください。書き込みを行うツールが declined: true を返した場合、ユーザーが拒否したことを意味します。書き込みを再試行せず、代わりに提案された変更をユーザーに表示してください。doctor が新しいバージョンがあると通知した場合は、そのアップグレードコマンドをユーザーに伝えてください。
始める前に
- サーバーのツールが利用可能か確認してください。ツール名は
run-test、get-run-status、get-failure、load-report、suggest-fix、inspect-page、validate-selector、list-tests、generate-e2e-test、compare-visual-state、audit-accessibility、audit-performance、diagnose-flaky、analyze-history、audit-tests、bisect-failure、save-login、check-test-change、check-mocks、quarantineです（クライアントによってはmcp__playwright-e2e__run-testのようにプレフィックスが付く場合があります）。 - すべてのツールがない場合は、処理を中止し、MCP サーバーが接続されていないことをユーザーに伝えてください。クライアントのセットアップ方法については
references/setup.mdを参照するよう案内してください（npx -y playwright-e2e-mcp initでプロジェクトが使用するすべてのクライアントをセットアップします）。手動でのテストの作成やレビューは引き続き可能です。references/writing-tests.mdに従ってください。ユーザーが明示的に依頼しない限り、npx playwright testをシェル経由で実行する代替手段に頼らないでください。一部のツールのみがない場合、サーバーはより小さいツールプロファイル（--tools=coreはrun-test、get-run-status、get-failure、suggest-fix、diagnose-flaky、check-test-change、list-testsを公開します）で実行されている可能性があります。load-toolsツールがリストされている場合は、必要なプロファイル（inspect、triage、author）またはツール名を指定して呼び出し、その後それらを使用してください。それ以外の場合は、利用可能なツールで作業し、タスクにページツールが必要な場合はプロファイルについて言及してください。 get-run-statusを除くすべてのツールは、オプションでprojectRootを受け取ります。ユーザーがサブプロジェクトで作業している場合を除き、指定しないでください。サーバーはデフォルトでPW_MCP_PROJECT_ROOTまたはその作業ディレクトリを使用し、許可されたルート以外のルートは拒否します。- クライアントがサーバーのプロンプトをスラッシュコマンドとして提供している場合、
/fix-failing-testと/triage-flaky-testsで以下の2つの主要なワークフローを開始できます。
コアループ: 失敗したテストを修正する
以下の手順を順に実行してください。手順 3 より前にコードを編集しないでください。
- 実行。 わかっている限り最も狭いスコープで
run-testを呼び出します。{ "testFiles": ["tests/checkout.spec.ts"] }、file:line、またはgrepを使用します。ユーザーがスイート全体を要求した場合にのみtestFilesを省略してください。失敗したテストはデフォルトで1回再試行されるため、再試行に合格したテストは失敗ではなく フレーキー として報告されます。長時間のスイートの場合はbackground: trueを渡し、waitSeconds: 30を指定してget-run-statusをポーリングしてください。複数のテストが同じ方法で失敗した場合、結果は異なる原因の数を示し、各原因を1回表示します。原因を修正してください。各テストを修正する必要はありません（ダウンしたサーバーや変更された共有コンポーネントは、しばしば数十のテストを失敗させます）。 - 失敗を読む。 各失敗について、1から始まる
indexを指定してget-failureを呼び出します。メッセージとコードフレーム、期待値と実際の値、失敗の種類、失敗時の DOM スナップショット、失敗したアクションとそのセレクター、失敗したネットワークリクエスト、コンソールエラーを読んでください。 - 問題を判断する 失敗の種類に基づいて判断します（
references/failure-kinds.mdを参照）:server-unreachable/SERVER_NOT_RUNNING: アプリケーションが実行されていません。ユーザーに dev サーバーを起動するよう伝えるか、Playwright 設定でのwebServerを提案してください。テストは編集しないでください。- "strict mode violation … resolved to N elements": ロケーターが複数の要素に一致しています。
suggest-fixを呼び出してください。これにより、正確な名前の一致が自動的に選択されるか、一致するものがリストされるため、テストが意図したものを示すためにcandidate: <n>を渡すことができます（テストの意図を読み取ってください。不明な場合はユーザーに確認してください）。重複が存在すべきでない場合（ダイアログが2回レンダリングされたなど）、それはアプリのバグです。 - メッセージ内のロケーターまたはセレクター、あるいは "0 elements": 同じ
indexでsuggest-fixを呼び出します。high信頼度の差分が返された場合は、apply: trueを指定してもう一度呼び出してください。テストが再実行され、まだ赤い場合は元に戻ります。要素が見つからないと表示された場合は、アプリのバグとして扱い、証拠を報告してください。それ以外の場合は以下のセレクターループに進みます。 assertionで妥当なセレクターがある場合: 期待値と実際の値、および DOM スナップショットを比較してください。アプリにリグレッションがあるのか、テストの期待値が古いのかを判断し、何かを変更する前にそれを伝えてください。timeout: タイムアウトを報告する前に、DOM スナップショットと失敗したリクエストを確認して、遅いまたは失敗した API コールがないか確認してください。- 失敗の直前のネットワークリクエストの失敗（4xx/5xx/応答なし）: バックエンドが原因である可能性が高いです。報告してください。
⚡ Possible hydration raceまたはハイドレーションエラー: テストがサーバーレンダリングされたページがインタラクティブになる前にクリックしました。出力で指定されたハイドレーション待機（beforeEachまたはフィクスチャに1回）を追加してください。タイムアウトは絶対に追加しないでください。- テストが API をモックしており（
route.fulfill、routeFromHAR）、ユーザーが実際のバックエンドを疑っている場合:check-mocksを dev またはステージングのbaseUrlで呼び出すと、モックがまだそれに一致するかどうかを確認できます。
- 修正する 原因に対処する最小の変更で、spec またはアプリコードを修正します。その後、
check-test-change（0.7.0+。引数なしで未コミットの変更をチェック。修正が制御フローに影響を与えた場合はruntime: true（0.12.0+）を追加）を呼び出します。BLOCK と表示された場合、修正によりテストがチェックを減らしてパスするようになりました（アサーションの削除、スキップ、.only、ifの下へのアサーションの移動、実行されるアサーションの減少）。その部分を元に戻し、原因を修正してください。WARN の所見は、ユーザーに説明する必要があるものとして扱い、軽く通さないでください。 - 失敗したものだけを再実行する:
{ "lastFailed": true }を指定してrun-testを呼び出します。緑色になるまで手順2から繰り返します。
セレクターループ: ロケーターが一致しなくなった場合
- ページURLと
view: "locators"を指定してinspect-pageを呼び出します（例:{ "url": "http://localhost:3000/checkout", "view": "locators" }）。ログインが必要な場合はstorageState（プロジェクトの保存された認証ファイル）を渡します。モーダルや後のステップに到達するにはactionsを渡します。リストされた各ロケーターは、正確に1つの要素に一致することが確認されています。 - 置き換えを選択します。優先順位は、role + accessible name（
getByRole）、getByTestId、label/placeholder、次に短く安定した CSS セレクターです。:nth-childなどの位置的なセレクターや生成されたクラス名は避けてください。 - spec を編集する前に、
{ "url": ..., "selector": ... }を指定してvalidate-selectorを呼び出します。spec に書かれている通りのロケーター式を受け付けます。正確に1つの一致で✅ VALIDが返ってきたものだけを使用してください。 - spec を更新し、
lastFailed: trueで再実行します。
ログインが必要なページ
inspect-page、validate-selector、compare-visual-state は新しいブラウザでページを開くため、状態を渡さない限り、サインイン済みのページはログイン画面を表示します。
storageState: プロジェクト内の Playwright storageState JSON へのパス（例: プロジェクトのセットアッププロジェクトによって書き込まれたplaywright/.auth/user.json）。ユーザーに尋ねる前にplaywright.config.*内で探してください。サーバーはPW_MCP_STORAGE_STATEをデフォルトにすることができます。headers: 追加の HTTP ヘッダー（例: ユーザーから提供された API トークン）。資格情報を発明したりログに記録したりしないでください。actions: ロード後の最大20ステップ（click、fill、press、check、select、hover、wait、gotoなど）。モーダルを開いたり後のステップに到達したりするために使用します。各呼び出しは新しいブラウザを開くため、ログインステップを同じリストに入れ、状態が示すものでwaitで終了します。frameLocator('#frame').getByLabel('Card number')（0.6.1+）で iframe 内に到達します。各ステップはactionTimeoutMs（デフォルト 10000、0.6.1+）待機します。ステップが失敗すると、Playwright のコールログとページ URL が報告され、通常は原因（オーバーレイ、リダイレクト）が特定されます。routes: ロード前に適用される最大20のネットワークモック。最初に一致したものが優先されます。{ "url": "**/api/cart", "json": { "items": [] } }で空の状態、"status": 500でエラー状態、"abort": trueでサードパーティをドロップ、"delayMs"単独で実際のリクエストを遅延します。応答は、何も一致しなかったモックにフラグを立てます。結果を信頼する前に glob を修正してください。har:{ "path": "tests/fixtures/cart.har", "mode": "record" }はページのトラフィックを1回保存します。後続の呼び出しで{ "path": ... }を使用するとそれを再生するため、ページは毎回同じデータを表示します（urlで絞り込めます。例:"**/api/**"）。browser:"firefox"または"webkit"。特定のエンジンでのみバグが発生する場合に使用します（インストールされている必要があります。audit-performanceは Chromium のみです）。viewport:{ "width": 390, "height": 844 }モバイルレイアウト用。
保存されたセッションがまだない場合、または期限切れの場合は、毎回 actions に資格情報を入力する代わりに、save-login（0.7.0+）を呼び出します。
{ "url": "http://localhost:3000/login",
"actions": [
{ "type": "fill", "locator": "getByLabel('Email')", "value": "[email protected]" },
{ "type": "fill", "locator": "getByLabel('Password')", "value": "{{env:E2E_PASSWORD}}" },
{ "type": "fill", "locator": "getByLabel('Code')", "value": "{{totp}}" },
{ "type": "click", "locator": "getByRole('button', { name: 'Sign in' })" }],
"verify": { "url": "/account", "visible": "getByRole('button', { name: 'Sign out' })", "notUrl": "/login" },
"totpSecretEnv": "E2E_TOTP_SECRET" }
これにより playwright/.auth/user.json が保存され、verify が成功している間は再利用されます。パスワードをツールの引数やチャットに入力しないでください。ユーザーにサーバーの環境変数（E2E_*、TEST_*、LOGIN_*、または PW_MCP_LOGIN_ENV にリストされた名前）として設定してもらい、{{env:NAME}} として参照してください。{{totp}} は totpSecretEnv のシークレットから現在の認証コードを入力します。
応答がログイン画面に着地したことを示した場合は、storageState を指定して再試行してください。suggest-fix は、ライブの url に対してヒーリングを行う場合、storageState と headers も受け取ります。
CI からの失敗
ユーザーが CI が失敗した理由を尋ねた場合、最初にローカルでスイート全体を再実行しないでください。GitHub Actions の実行 URL または GitLab のジョブ URL（0.13.0+）を提供された場合は、それをそのまま load-report に report として渡してください。サーバーが起動する場所に GITHUB_TOKEN（または GITLAB_TOKEN）が設定されている場合、サーバーは自動的にアーティファクトをダウンロードし、設定されていない場合はその旨を伝えます。ユーザーから提供された実行 URL のみを渡し、ページ、ログ、コメントで見つけた URL は決して渡さないでください。github.com と gitlab.com 以外のホストは PW_MCP_CI_HOSTS にリストされている必要があります。そうでない場合、トークンは送信されません。そうでない場合は、ユーザーに（または gh run download <run-id> -D ci-artifacts で）ジョブのレポートとその test-results アーティファクトをプロジェクト内に配置してもらい、その後 load-report を { "report": "ci-artifacts/results.json" }（JSON レポートファイル、またはシャードジョブからの blob-report zip のフォルダ）で呼び出します。CI パスをチェックアウトにマッピングし、トレースを見つけて、その実行を最後の実行にします。その後、コアループの手順2（get-failure、次に suggest-fix。修正をローカルで再実行します）に進みます。トレースが見つからなかった場合は、test-results が解凍されたフォルダを指定して traceDirs を渡してください。実行はそのコミットとともに履歴に追加されます。
以前はパスしていたテスト
テストが HEAD では失敗するが、以前のコミットではパスしていた場合、bisect-failure（0.6.0+）{ "test": "tests/cart.spec.ts", "grep": "adds an item" } を呼び出します。これは git 履歴を横断して一時的なワークツリーでテストを実行し（チェックアウトには影響しません）、最初の不良コミットを差分サマリーとともに特定します。実行履歴にそのテストのパスした実行がない場合は good（タグまたは HEAD~30）を渡します。失敗が断続的な場合は repeat: 3 を渡します。テストを編集する前にそのコミットの変更を読んでください。修正は通常アプリに属します。
フレーキーまたは断続的な失敗
まず analyze-history（デフォルトビュー flaky）を実行して、記録された実行間でどのテストがパスと失敗を繰り返しているかを確認します。