qa-testing-playwright

QA テスト（Playwright）

コアドキュメント：

• https://playwright.dev/docs/best-practices
• https://playwright.dev/docs/locators
• https://playwright.dev/docs/auth
• https://playwright.dev/docs/api-testing
• https://playwright.dev/docs/test-retries
• https://playwright.dev/docs/test-snapshots
• https://playwright.dev/docs/trace-viewer
• https://playwright.dev/docs/test-sharding
• https://playwright.dev/docs/ci
• https://playwright.dev/docs/pom
• https://playwright.dev/docs/test-agents
• https://playwright.dev/docs/clock
• https://playwright.dev/docs/getting-started-cli
• https://playwright.dev/docs/test-components
• https://playwright.dev/docs/test-parallel#test-locks
• https://playwright.dev/docs/release-notes（固定する前に現在のバージョンを確認してください）

クイックリファレンス

必要なこと	移動先
Playwright ワークフローを実行する	## Workflow
デフォルト設定と作成ルールを適用する	## Defaults と ## Authoring Rules
不安定またはブロックされた実行をデバッグする	## Debugging Checklist と ## Execution Preflight
ツールの適合性、セレクター、不安定さのトリアージ順序、シャーディングのコストを判断する	## Expert Judgment
テンプレートとリファレンスを読み込む	## Resources と ## Templates

デフォルト

• E2E は薄く保ちます。重要なユーザージャーニーのみを保護し、カバレッジはユニット／インテグレーション／コントラクトテストに寄せます。
• ロケーターの優先順位：getByRole → getByLabel/getByText → getByTestId（フォールバック）。
• 待機：Playwright の自動待機と Web ファーストアサーションを利用し、スリープや時間ベースの待機は使いません。
• 分離：テストは単独で、並列で、任意の順序で実行できる必要があります。共有される可変状態をなくしてください。共有リソースを分離できない場合（外部サービス、グローバルなアカウント設定など）は、ファイル全体に workers: 1 や describe.serial を設定する代わりに、名前付きテストロック（1.63 以降：test(title, { lock: 'user-settings' }, fn)）を宣言してください。
• ローカル実行の方針：まずサーバー構成をひとつ選びます（共有の開発スタック、または Playwright が管理する webServer）。その後、正確な spec または名前付きバッチを指定し、--workers=1 で問題を切り分けます。
• フレーキーなテストへの対応方針：リトライはデバッグ用の手段です。再実行で成功した場合も失敗の兆候と捉え、根本原因を修正してください。
• CI のフレーキーなテスト：組み込みの failOnFlakyTests（1.52 以降）を優先します。カスタムレポーターのテンプレートはレガシーであり、1.52 より前のバージョンに固定している場合のみ使用します。
• CI の方針：PR ではスモークテストをゲートにし、回帰テストはスケジュールに従ってシャーディング／並列化します。アーティファクト（トレース／動画／スクリーンショット）は常に保持してください。
• オラクルの方針：ユーザーの目的が達成されたことをアサートします。画面上の結果を直接検証できる場合は、付随的なネットワークリクエストの完了を待たないでください。
• AI の方針：Playwright の codegen／テストエージェント／MCP は、ひな形の作成と探索に使用し、その後、アサーションとフィクスチャを手動で堅牢化します。
• コンポーネントテスト：@playwright/test（1.62 以降）に組み込まれたストーリー／ギャラリーの mount('components/X/Story') フィクスチャを使用します。@playwright/experimental-ct-* パッケージは 1.63 で凍結され、ドキュメントにも削除されたと記載されています。移行が完了するまでは 1.62 を使用してください。references/playwright-patterns.md#component-testing を参照してください。
• ビジュアルリグレッション：Docker 内の 1 つの OS／ブラウザのベースラインで十分な場合は、ネイティブの toHaveScreenshot を使用します。デザイナーが差分をレビューする場合や、ブラウザ／OS の組み合わせが多く、コミットするベースラインの管理が難しい場合は、ホスト型サービスを使用します。references/visual-regression-testing.md を参照してください。
• ブラウザー MCP：テスト生成とアクセシビリティには Playwright MCP を、パフォーマンス／ネットワーク／コンソールのデバッグには Chrome DevTools MCP を使用します。references/playwright-mcp.md を参照してください。
• CLI の方針：スループットを重視するコーディングエージェントでは、Playwright MCP より Playwright CLI（npx playwright cli、シェルコマンド）を優先してください。MCP プロトコルの呼び出しごとのトークンオーバーヘッドを避けられます。CLI の利用可否やフラグはリリースごとに異なるため、利用する前に npx playwright cli --version とリリースノートで、インストール済みのバージョンを確認してください。公式ドキュメントは数値を示さず、トークン効率が高いと説明しています。「タスクあたりのトークン数」の比較など、具体的なトークン数は引用可能な事実ではなく、自分で測定して検証すべき主張として扱ってください。永続的なブラウザー状態や豊富なイントロスペクションが必要な場合は、MCP（npx playwright mcp）を使用します。
• ローカルでの反復作業の方針：作成中に未コミットの変更やブランチの変更の影響を受けるテストのみを実行するには、npx playwright test --only-changed=main を使用します。これはインポートグラフに基づくヒューリスティックなので、マージ前には必ずフルスイート（またはデプロイゲートの再実行）を実行してください。--only-changed が成功しても、リリース準備完了の判断材料にはしないでください。

クイックスタート

コマンド	目的
npm init playwright@latest	Playwright を初期化する
npx playwright test	すべてのテストを実行する
npx playwright test --grep @smoke	スモークテストを実行する
npx playwright test --project=chromium	単一のプロジェクトを実行する
npx playwright test --ui	UI モードでデバッグする
npx playwright test --debug	テストをステップ実行する
npx playwright codegen	操作フローを記録し、テストのひな形を作成する
npx playwright init-agents --loop=claude	Claude Code 用のテストエージェントを初期化する（--loop=codex、vscode、opencode も利用できます）
npx playwright test --debug=cli	コーディングエージェントが playwright-cli 経由でテストに接続し、デバッグできるようにする（1.59+）
npx playwright test --last-failed	前回の実行で失敗したテストのみを再実行する
npx playwright test --fail-on-flaky-tests	不安定なテストが1つでもあれば CI を失敗させる
npx playwright show-trace trace.zip	トレース成果物を確認する
npx playwright show-report	HTML レポートを確認する
npx playwright trace open <trace.zip>	CLI 分析用にトレースを開く。その後、trace actions、trace action <n>、trace snapshot <n> --name after、trace close を実行する（1.59+）
npx playwright test --only-changed=main	main 以降の変更の影響を受けたテストのみを実行する（ヒューリスティックです。リリース前には必ず全テストを実行してください）

ローカル実行の構成

デフォルトでは、次の順序で進めてください。

1. リポジトリに共有のローカル開発スタックがすでに用意されている場合は、まずそれを1つ起動します。再実行ごとに新しいアプリを立ち上げるのではなく、--no-server を使って再利用することを優先してください。
2. リクエストを処理しているビルドを特定し、ソースリビジョンまたはビルド ID、ベース URL、サーバープロセス／起動コマンド、環境、サービスワーカーまたは CDN のキャッシュ状態を記録します。ポートがリッスン状態でも、古いコードを配信している場合があります。ビルドを特定できない場合は、結果に runtime observed, build identity unverified と明記してください。
3. 正確な spec を1つ、または名前を付けたバッチを1つ指定し、--workers=1 で再現します。
4. 影響を受ける最小範囲を修正して再実行します。
5. 対象範囲がすべて成功してから、デプロイゲートのリプレイを実行します。

デフォルトのスイートの段階：

• スモーク：PR ゲートで最速のシグナルを得るために使います。
• 対象バッチ／spec：ローカルでのトリアージや不安定なテストの解消に使います。
• デプロイゲートのリプレイ：リリースへの信頼性を高めるため、依存関係チェーンや重要なユーザージャーニーを再生します。

ジョブで「今すぐデプロイ可能であることを証明する」ことが明示的に求められていない限り、最初にローカルで全テストを再実行するのは避けてください。

使用する場面

• Web アプリケーションの E2E テスト
• ユーザー認証フローのテスト
• フォーム送信の検証
• レスポンシブデザインのテスト
• ブラウザー操作の自動化
• CI/CD での Playwright のセットアップ

使用しない場面

シナリオ	代わりに使用するもの
ユニットテスト	Jest、Vitest、pytest
API コントラクト	qa-api-testing-contracts
負荷テスト	k6、Locust、Artillery
モバイルネイティブアプリ	Appium
ビジネスロジックやデータ変換のみの正確性	ユニットテスト — ブラウザーを使うと、信頼性が高まらないまま遅延と不安定さが増します
チーム間での API コントラクトの不整合	UI のクリック経路で代用せず、コンシューマー主導のコントラクトテストを使います
大規模なコンポーネント単位のビジュアル／操作の分離テスト	すでに Playwright を実行している場合は、Playwright のストーリー／ギャラリーコンポーネントテスト（1.62+、安定版）。ホストされた UI でチームがビジュアル差分をレビューする場合は、Storybook + Chromatic/Percy を使います（「デフォルト」を参照）
数千通りの入力の組み合わせを使ったファジング	ユニット層でプロパティベーステストを使います。E2E では実行時間が許容できません

エキスパートの判断

Playwright が適切でない場合

同じリスクをより高速かつ低コストのレイヤーですでに検証できる場合、Playwright（またはその他のブラウザー E2E ツール）は適切ではありません。

• 型システム、単体テスト、スキーマ／コントラクトチェックで検出できる種類のバグは、より下位のレイヤーで検出してください。E2E はアサーションあたりのコストが最も高いテストレイヤーです（ブラウザーの起動、ネットワーク、レンダリング）。
• 「ユーザージャーニー」が、意味のある UI の分岐を伴わない内部 API 呼び出しにすぎない場合は、API を直接テストし（request フィクスチャまたは専用の API テスト用スキルを使用）、ブラウザーは使わないでください。
• 管理していないサードパーティの画面（決済プロバイダーのホストページ、OAuth 同意画面など）をテストする場合は、E2E で追いかけないでください。境界をモックし、代わりに独自の統合コントラクトをテストしてください。サードパーティの UI 変更によってテストが不安定になるのは、設計上の問題であり、偶然ではありません。
• コンポーネントテストやビジュアルスナップショットですでに同じリスクをはるかに低いコストでカバーできている場合、「念のため」E2E にも重複して追加しないでください。リスクを重複させずにカバレッジだけを重複させるのは、徹底ではなく無駄です。

セレクター戦略の判断ルール

次の順にロケーターを選び、曖昧さなく要素をちょうど 1 つ特定できた時点で選択を止めてください。

1. アクセシブルな名前を指定した getByRole — スクリーンリーダーと実際のユーザーの両方がこれを基準にするため、マークアップをリファクタリングしても機能します。
2. getByLabel ／ getByText — 意味のあるロールがない場合（通常のテキスト、装飾用コンテナーなど）に使用します。ただし、表示テキストが安定していることが条件です。
3. getByTestId — 要素に安定したロールやラベルがない場合（例：キャンバス、ドラッグハンドル、同じ名前のリスト項目）、またはセマンティックなロケーターでは実装の詳細（生の CSS クラス、生成された ID）をアサーションせざるを得ない場合に限って使用します。 最初から生の CSS や XPath に頼らないでください。これらは単なるテスト上の回避策ではなく、マークアップ自体にアクセシビリティの修正が必要かもしれないという兆候です。

フレーキーテストの切り分け順序（シグナルが早い順）

アサーションに手を加える前に、以下の順序で失敗を分類してください。各ステップは次のステップよりも厳密に低コストなので、先に進まないでください。

1. セレクターの曖昧さ — トレースでロケーターが要素を0個または2個以上検出したことを確認します。待機ではなく、ロケーターを修正してください。
2. 待機不足／競合状態 — 要素が操作可能になる前にアクションが実行されたことがトレースに示されている場合です。Web ファーストアサーションに置き換えてください。固定時間のスリープは決して追加しないでください。
3. 状態の漏えい — 他のテスト実行後にのみ失敗が再現する場合です（並列ワーカー、共有フィクスチャ、削除されていないテストデータ）。このテスト自体のコードに手を加える前に、分離を修正してください。共有リソースを分離できない場合は、スイートを直列化するのではなく、そのリソースに触れるテストだけに名前付きの lock を設定してください（1.63+）。
4. 環境 — CI でのみ失敗し、ローカルでは失敗しない場合です。プロダクトのバグと判断する前に、同時実行数、コールドスタート、CPU の枯渇、コンテナーのリソース制限を確認してください。
5. ステートフルアプリのクラス — 認証中心またはバックエンド駆動型のアプリでは、プロダクトのバグと判断する前に、auth-state、state-sync、optional-network、degraded-mode も分類してください（「### ステートフルアプリの失敗クラス」を参照）。
6. プロダクトのリグレッション — 1〜5 がトレースの証拠によって除外された場合に限り、テスト対象アプリの問題として扱い、適切に報告または修正してください。 リトライはこれらすべてを覆い隠します。最初の CI 実行で証拠（トレース／動画）を収集するために retries を使ってください。ただし、「リトライで成功」は未解決の不具合であり、合格ではありません（failOnFlakyTests: true）。

フレーキーテストの調査ツール（固定バージョンで利用可能か確認してください）：

• retryStrategy: 'isolated'（1.62+）は、すべてのリトライを最後にまとめ、単一のワーカーで1つずつ実行します。スイート内では失敗しても分離実行では成功するテストは、干渉（ステップ3）を示唆します。分離実行でも失敗する場合は、ステップ1、2、または6が疑われます。
• trace: 'retain-on-failure-and-retries'（1.59+。1.61以降は video モードも使用可能）を使うと、失敗した試行と成功した試行の両方が保持され、並べて比較できます。
• 疑わしいテスト単体に対する --repeat-each=N で修正を検証できます。--last-failed は直前に失敗したテストのみを再実行します。
• 隔離：オーナーと終了日を指定して @flaky をタグ付けし、--grep-invert @flaky または Reporter.preprocess() のスキップリスト（1.62+）を使ってゲートから除外します。オーナーのいない隔離テストは、削除されたテストと同じです。

CI の並列実行にかかるコスト（計算例）

シャーディングではマシンコストと実行時間を引き換えます。判断に必要な計算は簡単です。シングルスレッドで T 分かかるスイートを、各シャードでチェックアウト、インストール、ブラウザーのダウンロードといった固定オーバーヘッドに M 分のマシン時間を要する N 個のシャードに分割するとします。

• シャードごとの実時間 ≈ T/N + M。
• 課金対象となるマシン時間の合計 ≈ N × (T/N + M) = T + N×M。

例：T = 60 分、シャード／ジョブごとの固定オーバーヘッド M = 3 分の場合。

• 1シャード：実時間 = 63分、課金対象 = 63マシン分。
• 4シャード：実時間 = 60/4 + 3 = 18分、課金対象 = 4 × 18 = 72マシン分。
• 12シャード：実時間 = 60/12 + 3 = 8分、課金対象 = 12 × 8 = 96マシン分。

固定オーバーヘッドはN回発生するため、シャーディングではマシン時間の合計が必ず増えます。得られるのはPRへのフィードバックの高速化であり、コスト削減ではありません。判断の目安として、PRゲートのスモークテストスイートはシャーディングします（実時間が重要で、スイートも小さいため N×M は小さく収まります）。一方、完全なリグレッションテストはスケジュールに沿ってシャーディングせずに実行するか、少数のシャードに分割します（こちらは遅延よりコストのほうが重要です）。シャード数を決める前に、独自の T と M でこの比率を計算してください。慣例だからといって N=4 をそのまま使わないでください。

作成ルール

ロケーター戦略

// 1. Role locators (preferred)
await page.getByRole('button', { name: 'Sign in' }).click();

// 2. Label/text locators
await page.getByLabel('Email').fill('[email protected]');

// 3. Test IDs (fallback)
await page.getByTestId('user-avatar').click();

フレーキーテスト対策

• スリープは避け、Playwright の自動待機を使用する
• リトライは補助ではなく、シグナルとして使う
• CI では組み込みの failOnFlakyTests を優先する
• 失敗時にトレース／スクリーンショット／動画を記録する
• ユーザーらしい操作を優先し、force: true は避ける

ワークフロー

• ユーザーの成果（意図と判定基準）を証明する、最小のテストを書きます。
• トリアージの前に、実行構成を明確にします。共有開発スタックを使うのか、Playwright の webServer を使うのかを決め、開始・停止の正確なコマンドも確認します。
• 範囲を広げる前に、正確なテスト仕様を1つ、または名前を指定したバッチで再現します。
• 手順を増やす前に、ロケーターとアサーションを安定させます。
• 状態を明示します。テスト／ワーカーごとにシードデータを用意し、確実にクリーンアップして、状態を持つアプリでは認証／サブスクリプション／テストデータのリセット経路を検証します。
• ユーザー向けの判定基準に含まれない場合は、サードパーティとの境界をモックするか、切り離します。
• CI では、シャーディング／並列化し、アーティファクトを取得して、再実行で成功する不安定なテストは速やかに失敗させます。

デバッグチェックリスト

不安定な場合：

• まずトレースとエラーのアーティファクトを開き、失敗の原因がセレクターの曖昧さ、待機不足、状態の漏れ、誤ったサーバー構成のどれかを特定します。
• トレースがログイン画面や予期しないリダイレクトに移動した場合は、アサーションを変更する前に auth-state と分類します。
• ブラウザーのログにサイドエンドポイントの 429 または Retry-After が記録されている場合、そのリクエストが判定基準の一部なのか、単なるノイズなのかを判断します。
• もろいセレクターをセマンティックロケーターに置き換え、スリープを expect(...)、認証状態を考慮したナビゲーションヘルパー、または対象を絞った準備完了アサーションに置き換えます。
• 付随的なリクエストの待機をなくし、代わりに表示されるルート、アクション、またはコンテンツの結果をアサートします。
• グローバルタイムアウトを短縮し、本当に必要な場合に限ってスコープ付きタイムアウトを追加します。playwright.config.ts で timeout を増やすより、アクション単位のタイムアウト、または test.step(name, fn, { timeout }) を優先します。
• CI でのみ失敗する場合は、並行処理、コールドスタート、CPU の枯渇、環境の違いを調べます。

実行前チェック

コストの高い E2E テストを実行する前に、references/playwright-preflight-sandbox.md にある事前チェック（テスト仕様のパス、ポート／ホストのバインド、単一のサーバー構成、ビルドロック、テストごとのタイムアウト予算、EPERM／EACCES のエスカレーション）を実施し、assets/template-playwright-preflight-checklist.md を使って回答を記録します。EADDRINUSE、テスト仕様／結果パスの欠落、角括弧付きルートセグメントでのシェル glob の失敗は、プロダクトのバグではなく環境の問題として扱います。

状態を持つアプリの失敗分類

• auth-state：保護されたルートが予期せずログイン画面にリダイレクトされる、またはストレージ／セッション状態が失われる。
• state-sync：バックエンドのリセットまたは Webhook は成功したものの、UI がまだ反映されていない。
• optional-network：サイドリクエストは失敗したものの、ユーザーから見える判定結果は正しい可能性がある。
• degraded-mode：レート制限またはフォールバック UX が有効になっており、意図的にアサートする必要がある。

リソース

リソース	用途
references/playwright-mcp.md	MCP と AI のテスト
references/playwright-patterns.md	高度なパターン
references/playwright-ci.md	CI の構成
references/playwright-authentication.md	認証パターンとセッション管理
references/visual-regression-testing.md	ビジュアルリグレッション（ライブラリの標準）：ネイティブとホステッド、ベースライン、しきい値
references/api-testing-playwright.md	UI と API を組み合わせたテスト用の request フィクスチャ（コントラクト／スキーマの作業は qa-api-testing-contracts にあります）
references/playwright-preflight-sandbox.md	サンドボックス／ポートの事前チェックとエスカレーションの判断
data/sources.json	ドキュメントへのリンク

テンプレート

テンプレート	目的
assets/template-playwright-e2e-review-checklist.md	E2E レビューチェックリスト
assets/template-playwright-fail-on-flaky-reporter.js	レガシー：Playwright < 1.52 の場合のみ、再実行で成功する不安定なテストで CI を失敗させます。それ以外の場合は failOnFlakyTests を使用してください
assets/test-fail-on-flaky-reporter.test.js	レガシーな不安定テストレポーターの node --test チェック
assets/template-playwright-preflight-checklist.md	ポート／サンドボックス／タイムアウトの事前確認チェックリスト

ナビゲーション

クイックリファレンスを使って、ワークフロー、デバッグ手順、またはリソースを選択してください。

関連スキル

スキル	目的
qa-testing-strategy	テスト戦略全般
software-frontend	フロントエンド開発
ops-devops-platform	CI/CD 統合

検証ゲート

提出前に、以下を確認してください。

• Playwright プロジェクトが存在する場合、実行する正確なテストコマンドを提示し、環境が利用可能であれば実行してください。そうでない場合は、実行結果が未検証であることを明記してください。
• 生成されたセレクターは、ページの制約で不可能な場合を除き、指定されたロケーターの優先順位に従っています。
• 出力にスリープベースの待機が含まれておらず、確認すべき準備完了アサーションまたはトレース／デバッグ用アーティファクトが明記されています。
• 参照されているすべてのテストファイル、設定ファイル、コマンドパスがリポジトリに存在するか、提案として明示されています。

学びのループ

過去の決定や落とし穴が関係する場合は、存在すれば learnings.consolidated.md を参照してください。必要な履歴を確認する場合、または利用可能な代替資料として learnings.md を使用してください。どちらも該当しない場合は、両方とも参照しないでください。

適用後、記録しておく価値のあるパターン、防止すべきミス、または意外だった分野の知見に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って learnings.md に日付付きの箇条書きを1つ追加してください。SKILL.md 自体は変更しないでください。