playwright

Playwright

作業が Playwright Test、ブラウザー自動化、E2E テスト、ロケーター、フィクスチャ、認証のセットアップ、ネットワークのモック、トレース、CI、UI と併用する API テスト、コンポーネントストーリー、または Playwright を使ったエージェント向けブラウザーツールに関わる場合は、このスキルを使用してください。

スナップショット：@playwright/[email protected] / [email protected] / [email protected]（2026-10-01 時点で現行であることを確認）。バージョンが異なる場合は、source-map.md を参照して更新してください。

ワークフロー

1. コードを変更する前に、ローカルの Playwright の状況を確認します。
   • @playwright/test、playwright、任意の @playwright/browser-*、残存する @playwright/experimental-ct-*、Node、Docker イメージタグのパッケージバージョン。
   • 設定：playwright.config.ts / .js、testDir、プロジェクト、use オプション、webServer、レポーター、リトライ／retryStrategy／ワーカー。
   • テストの構成：spec、セットアッププロジェクト、フィクスチャ、POM クラス、playwright/.auth、スナップショット、ストーリー／ギャラリー、CI ワークフロー。
   • 実行時の目的：E2E UI、API のみ、認証の再利用、ネットワークモック、ビジュアル／a11y チェック、コンポーネントストーリー、エージェントによる探索。
2. ユーザーが最新の動作を求めている場合、バージョンが不明な場合、または CI、CT、エージェントツールに関わる作業の場合は、ドキュメントを更新します。source-map.md から始めてください。
3. インストール、Library と Test の違い、設定、プロジェクト、webServer、CLI については、setup-core.md を使用してください。
4. ロケーター、アクション、自動待機、Web ファーストアサーション、アンチパターンについては、locators-assertions.md を使用してください。
5. フィクスチャ、POM、認証／storageState、並列実行、テストロック、ネットワーク／HAR モックについては、fixtures-auth-network.md を使用してください。
6. トレース、UI Mode、デバッグ、CI／シャーディング／Docker、API テスト、CT、a11y／ビジュアル、エージェントツールについては、debugging-ci-advanced.md を使用してください。
7. 既存のプロジェクトスタイルに沿って実装します。
   • E2E には @playwright/test を優先してください。Test Runner を使わない単独のスクリプト／自動化では、playwright ライブラリを使用してください。
   • Playwright パッケージのバージョンを変更した後は、対応するブラウザーバイナリを再インストールしてください。
   • 公式ガイダンスに反しない限り、ローカルのロケーター規約、フィクスチャのパターン、CI のアーティファクト設定に合わせてください。

Playwright の判断基準

• ユーザー向けロケーターを優先します。まず getByRole、次にラベル／プレースホルダー／テキスト／alt／タイトル、最後に getByTestId を使います。正当な理由がない限り、CSS／XPath は避けてください。
• :visible CSS 疑似クラスより locator.visible() を優先します。仕様上可能な場合は、表示状態で絞り込むより、一意のロール／名前を優先してください。
• 対象がどの iframe 内にあるか分からない場合に限り、セレクターなしで page.frameLocator() を使います。残りのロケーターも、単一のフレーム内で解決される必要があります。
• await expect(...).toBeVisible() などの Web ファーストのアサーションを使います。expect(await locator.isVisible()).toBe(true) は使わないでください。
• 自動待機を信頼してください。waitForTimeout やスリープベースの同期処理を含めないでください。
• テストは分離してください。すべてのテストで共有の変更可能なログイン状態を使うのではなく、setup プロジェクトの storageState またはワーカー単位のアカウントを優先してください。
• 外部リソースを共有する場合は、ファイル全体を直列化するのではなく、名前付きの lock を宣言してください。デフォルトモード／直列モードでは、1 つのテストに設定されたロックはファイル全体の実行中に保持されます。
• サードパーティーまたは制御できないネットワークは context／page.route でモックしてください。トリガーとなる操作の前に waitForResponse を開始してください。
• ローカルでのデバッグ手順：UI Mode → CI の失敗には Trace Viewer → ステップ実行には --debug／Inspector。
• CI のデフォルト設定：forbidOnly、リトライ、trace: 'on-first-retry'、screenshot: 'only-on-failure' を使用します。--with-deps またはバージョンを一致させた Docker イメージ（mcr.microsoft.com/playwright:v1.63.0-noble）でインストールし、ワーカーだけでなくシャードでスケールしてください。
• コンポーネントテストでは、アプリ独自の開発サーバーが配信するストーリーギャラリーに対して、組み込みの mount を使います。1.63 以降では @playwright/experimental-ct-* を追加しないでください。これらのパッケージが移行されるまでは 1.62 を使用してください。
• リポジトリ内でテストを書くコーディングエージェントには、利用可能な場合は Playwright CLI を優先し、ブラウザーを使ったライブ探索ループには Playwright MCP を使ってください。ハーネスのブラウザーツールと @playwright/mcp を混同しないでください。

検証

リポジトリに既存のチェックがある場合は、そちらを優先してください。重要な Playwright の作業では、該当するものを次の中から実施してください。

• 変更した spec／プロジェクトに絞った bunx playwright test（--project、ファイルパス、または -g タイトルを使用）。
• ロケーターやタイミングの挙動が不明確な場合は、UI Mode または headed 実行。
• フレーク、操作可能性、ネットワーク障害がある場合は、トレースまたは HTML レポートを確認。
• リトライ、シャード、レポーター、Docker タグ、認証のセットアップ、または webServer を変更する場合は、CI に近いスモークテスト。
• スナップショットの更新（-u）は、ビジュアルベースラインを意図的に変更する場合に限ります。可能であれば、CI と同じ OS／ブラウザーで生成してください。
• プロジェクトでテストの型チェックを行う場合は、TypeScript の設定、フィクスチャー、POM ヘルパーを型チェックしてください。