playwright

Playwright ブラウザー自動化

このスキルでは、Playwright で実際のブラウザーを操作します。エンドツーエンドテストの作成、セレクターとテストの堅牢化、ネットワークトラフィックのインターセプトとモック、複数の並列ワーカーや CI でのテストスイート実行、ヘッドレスモードでのスクレイピングとデータ抽出、スナップショットスキャンによるアクセシビリティチェックに利用できます。これは、名前の付いた 1 つのツールを対象とするツールスキルです。テスト戦略とフレームワークの選定についてはqa-methodologyを、フロントエンドコンポーネントとアーキテクチャの設計についてはfrontend-engineeringを参照してください。このスキルでは、Playwright ツール自体の操作を扱います。

操作上の契約

1. 実行前にテストスイートを読む。 何かを実行する前に、playwright.config.*、プロジェクト、baseURL、webServer、ワーカー、再試行、レポーターを確認してください。README に記載されたテストコマンドを前提にしてはいけません。
2. レイアウトではなく動作で特定する。 マークアップに依存する CSS／XPath より、ユーザー向けロケーター（getByRole、getByLabel、getByText）を優先してください。ユーザーから見える動作に基づくテストはリファクタリング後も有効ですが、構造に依存するテストは変更によって壊れます。
3. 境界でモックする。 外部 HTTP は page.route() でスタブ化し、ページ内のコードを書き換えてはいけません。テスト対象の依存関係を境界でモックし、テスト対象のコード自体はモックしないでください。検証すると主張する対象をモックしたテストでは、何も証明できません。
4. 意図を持って並列化する。 Playwright は各テストに分離されたブラウザーコンテキストを用意します。マシンとテストスイートに合わせて workers とシャーディングを調整し、グローバル変数を介してテスト間で可変状態を共有しないでください。
5. 境界で検証する。 テストが成功していても、アサーションが弱ければ十分な保証にはなりません。実装の詳細ではなく、ユーザーから見える結果（表示テキスト、URL、有効／無効の状態）を検証してください。
6. 証拠の量を制限する。 トレース、スクリーンショット、動画は失敗時のみ取得してください。JSON レポートは要約し、HTML 全体のダンプやセッション Cookie をチャットに貼り付けないでください。

pwrun スクリプト

scripts/pwrun は、Playwright テストスイート向けのエージェント優先のスモークテスト用ハーネスです。doctor、inventory、report は node や Playwright がインストールされていなくても動作するため、エージェントはどこからでもテストスイートを調査し、CI レポートをトリアージできます。

scripts/pwrun doctor --json                     # node, @playwright/test, browsers, config availability
scripts/pwrun inventory --json                  # config, projects, spec files in the suite
scripts/pwrun report --report test-results.json --json   # summarize a Playwright JSON report
scripts/pwrun smoke --url http://localhost:3000 --json   # delegate a smoke run to npx playwright test

終了コード：0 は成功、1 は分析エラー、2 は使用法エラー、127 は依存関係（node／playwright）の不足、124 は委譲先のタイムアウトです。すべてのコマンドで --json を使用できます。--help はツールチェーンがなくても動作します。

smoke では、--config が Playwright にそのまま渡されます。対象 URL の優先順位は、--url、継承した PW_SMOKE_URL、継承した BASE_URL、http://localhost:3000 の順です。選択した対象は、指定されたスキャフォールドに PW_SMOKE_URL として渡されます。JSON の結果では、requested_url と navigation_evidence が分けて記録されます。同梱のサンプルスペックは page.goto() の後に到達した URL を記録します。カスタムスペックで同じ実行時の証拠を提供するには、pwrun-navigation アノテーションが必要です。requested_target_origin_observed は、記録されたナビゲーションが要求されたオリジンに到達したかどうかを示します。

E2E テストの作成

• test.describe ブロック、test.beforeEach によるセットアップ、機能ごとのフィクスチャファイルでテストスイートを構成します。各スペックは簡潔にし、1 つのユーザージャーニーに絞り、文章のように読みやすくしてください。
• Playwright の Web ファーストアサーション（expect(locator).toBeVisible()、.toHaveText()、.toHaveURL()）を使用してください。これらはタイムアウトまで自動で再試行され、安定した E2E テストの基盤となります。手動で page.waitForTimeout を使って待機するのは避けてください。
• 設定の webServer でテスト対象のアプリを起動するか（Playwright が起動し、準備完了を待ってから終了します）、スモークテストでは baseURL を介してすでに起動中のインスタンスを再利用します。
• テスト作成のパターン、フィクスチャ、ページオブジェクトモデルについては、references/01-e2e-authoring.md を参照してください。

セレクターの堅牢性

• ロール、ラベル、テキスト、プレースホルダーのロケーターをデフォルトで使用します。これらはユーザーと同じ視点でページを表します。CSS はレイアウトに関連する用途（例：テスト専用の ID に対する getByTestId）に限って使用してください。
• 長くて壊れやすいセレクターを組み立てるのではなく、ロケーターを連結して絞り込みます（getByRole('row').filter({ hasText: 'Acme' })）。古くなった要素ハンドルを保持せず、改めてクエリしてください。
• 不安定なテストを修正するには、スリープや first() を追加するのではなく、どのセレクターが複数またはゼロの要素に一致したかを特定します。誤った要素に一致する可能性のあるセレクターは、いずれ問題を引き起こします。
• セレクターの優先順位ルールと不安定なセレクターの修正フロー：references/02-selectors.md。

ネットワークのインターセプトとモック

• page.route() でリクエストをインターセプトし、応答、ブロック、または継続を行います。サードパーティ API のモック、フィクスチャの注入、オフラインや低速ネットワークのエミュレート、テストを汚染するアナリティクスやトラッカーのブロックに使用します。
• リアルな本文とコンテンツタイプを使用して、ルートレベルでモックします。テスト対象として検証するサーバーはインターセプトしないでください。また、テストが依存する page.goto のナビゲーションを上書きするルート設定は行わないでください。
• page.on('request')／page.on('response') でリクエストを記録し、アプリが実際に送信した内容を検証します。パターンと注意点：references/03-network-interception-and-mocking.md。

並列ワーカー

• workers はスペックを実行する並列プロセス数を設定します。fullyParallel を有効にすると、すべてのスペックファイルをワーカー間で実行できます。可能な限り増やすのではなく、CPU 数とブラウザーのメモリに合わせて調整してください。
• 大規模なテストスイートでは、CI ジョブ間でスイートをシャードします（--shard=1/4）。各テストは専用のブラウザーコンテキストで実行されるため、デフォルトで分離されています。その状態を維持し、共有グローバルや共有ストレージ状態、テストの実行順序への依存を避けてください。
• ワーカー数、シャーディングの計算方法、分離に関する落とし穴：references/04-parallel-workers-and-sharding.md。

CI 連携

• 実行環境にブラウザーと OS 依存関係をインストールし（npx [email protected] install --with-deps）、Playwright のバージョンを固定して、~/.cache/ms-playwright をキャッシュします。
• webServer、retries（CI でのみ不安定なテストを再試行）、trace: 'on-first-retry' を設定して、失敗をデバッグできるようにします。html／json／github でレポートを作成し、失敗時にはアーティファクトをアップロードします。
• JSON レポートから CI の失敗をトリアージするには、scripts/pwrun report --json を実行します。ブラウザーを開かずに統計、失敗したスペック、エラーメッセージを要約できます。CI の詳しい設定例：references/05-ci-integration.md。

スクレイピングとヘッドレスブラウジング

• ブラウザー API（chromium.launch({ headless: true })、newContext、page.goto）を直接操作して JavaScript で描画されるページを読み込み、ロケーターと innerText／属性へのアクセスで構造化レコードを抽出します。抽出、検証、保存を行ってください。
• robots.txt、利用規約、レート制限を遵守し、ページ数と遅延時間に上限を設けてスクレイピングしてください。Cloudflare／DDoS-GUARD のチャレンジを回避する場合は flaresolverr を利用してください。このスキルではチャレンジを解決できません。
• スクレイピングのフロー、ページネーション、適切なデータ抽出：references/06-scraping-and-headless.md。

アクセシビリティスナップショットのチェック

• @axe-core/playwright で全ページをスキャンし、CI または必要に応じて WCAG 違反（コントラスト、ランドマーク、ARIA の誤用）を検出します。
• Playwright の aria スナップショット（expect(page).toMatchAriaSnapshot()）を、安定性とアクセシビリティを考慮したアサーションとして使用します。アクセシビリティツリーを比較するため、構造やラベルのリグレッションを検出でき、仕様に基づくアサーションのように読みやすくなります。意図的に更新し、--update-snapshots を安易に使用しないでください。
• スキャンの設定、スナップショットの適切な運用、違反の修正：references/07-accessibility-and-debugging.md。

ヘッド付きデバッグ

• ヘッド付きで実行（--headed）するか、--slow-mo で操作を遅くするか、--debug ／ PWDEBUG=1 と page.pause() のブレークポイントを使ってインスペクターを開きます。
• npx [email protected] codegen <url> でテストのひな型を生成し、生成されたセレクターをユーザー向けのロケーターに強化します。
• テストが失敗した場合は、トレース（--trace on）を読みます。失敗した操作について、ネットワーク、DOM スナップショット、コンソールが記録されています。まず scripts/pwrun report --report <json> --json を使って、失敗の概要を確認します。
• デバッグのワークフローについては、references/07-accessibility-and-debugging.md を参照してください。

リファレンスの参照先

次の場合に読み込み	リファレンス
仕様、フィクスチャ、ページオブジェクトの作成または構成	references/01-e2e-authoring.md
セレクターが不安定、または誤った要素に一致する	references/02-selectors.md
API／ネットワークトラフィックのモックまたは傍受	references/03-network-interception-and-mocking.md
大規模なテストスイートの高速化またはシャーディング	references/04-parallel-workers-and-sharding.md
Playwright の CI への組み込み、または CI の失敗のトリアージ	references/05-ci-integration.md
ヘッドレスモードでのデータ抽出またはブラウジング	references/06-scraping-and-headless.md
アクセシビリティスキャン、aria スナップショット、または失敗したテストのデバッグ	references/07-accessibility-and-debugging.md
ソース、バージョンに関する確認事項、更新手順	references/00-source-index.md

含まれる成果物

• scripts/pwrun：スモークテスト用ハーネス — doctor、inventory、report、smoke。すべて --json に対応しています。
• tests/test_pwrun.py + tests/fixtures/sample-report.json：ハーネス用の再現性のあるテスト（node／ブラウザーは不要）。
• tests/test_pwrun_scaffold.py：範囲を限定したローカルサーバー／ブラウザーの統合チェック。@playwright/test と Chromium がインストールされている場合に実行します。
• templates/playwright.config.ts、templates/example.spec.ts、templates/accessibility.spec.ts：コピーして使えるテストスイートのひな型。
• references/：上記の運用トピックを網羅する、日付とソースインデックス付きのリファレンス 8 件。

検証の基準

主張	最低限必要な証拠
ツールチェーンが利用可能	scripts/pwrun doctor --json に node、@playwright/test、ブラウザーが利用可能と表示される
テストスイートを把握している	scripts/pwrun inventory --json に構成ファイルと spec ファイルが一覧表示される
テストが合格する	対象の spec に対する npx [email protected] test の終了コードが 0（または smoke への委譲）
CI の失敗の原因が説明されている	scripts/pwrun report --report test-results.json --json に失敗した spec とエラーが表示される
アクセシビリティが網羅されている	axe スキャンが、宣言された重大度における違反ゼロで実行され、aria スナップショットが一致する
対象のフローにリグレッションがない	構成済みのワーカー／シャーディングでテストスイートが実行され、想定内／不安定／想定外の件数が記録されている

厳守事項

• テストを成功させるために、テスト対象のコードをモックしてはいけません。モックするのは境界部分だけです。
• robots.txt、利用規約、レート制限に違反するスクレイピングをしてはいけません。認証情報や個人データを収集してはいけません。また、認証／セッションのストレージをコミット対象のファイルに抽出してはいけません。
• playwright/.auth/* のストレージ状態、.env、ブラウザーの認証情報をコミットしてはいけません。
• aria スナップショットの差分を「修正」するために、確認せず --update-snapshots を実行してはいけません。まず変更内容を確認します。
• 保護されたコンテンツの生 HTML、トレースファイル全体、スクリーンショットをチャットに貼り付けてはいけません。代わりに pwrun report で要約します。
• CI でヘッド付きブラウザーを使うにはディスプレイサーバー（例：xvfb）が必要です。ランナーにディスプレイがあると決めつけてはいけません。

使用しないケース

• テスト戦略、フレームワークの選定、QA プロセス — qa-methodology を参照してください。
• フロントエンドのコンポーネント／状態／アーキテクチャの設計や実装ガイダンス — frontend-engineering を参照してください。React 固有のコンポーネントやフックに関する作業は react を参照してください。
• Cloudflare／DDoS-GUARD のチャレンジ回避 — flaresolverr を参照してください。
• 大規模な負荷／パフォーマンステスト（k6、Locust、Gatling、JMeter）— このテスト手法については、qa-methodology のパフォーマンステストのリファレンスを参照してください。
• 静的コンテンツの HTTP による直接取得 — 通常の HTTP クライアントを使用してください。Playwright は JavaScript でレンダリングされるページやブラウザのワークフロー向けです。

トピックの対象範囲を示すキーワード

カタログの自動トピックスキャンでは、対象範囲を示すキーワードを探すためにこのファイルを grep します。スキャンで両方の表記が一致するよう、以下にエイリアスのペアをそのまま記載しています。 e2e|end-to-end はブラウザレベルのテストを対象とします（E2E、end-to-end、e2e はいずれも同じワークフローです）。また、debug|head はこのスキルにおけるヘッデッドデバッグのワークフローを対象とします。その他のトピック（セレクターの堅牢性、ネットワークインターセプト、並列ワーカー、CI 統合、スクレイピング、アクセシビリティスナップショット、モック）は、上記の各セクションに名前が記載されています。