playwright-best-practices

Playwright のベストプラクティス

CLI コンテキスト：コンテキストのオーバーフローを防ぐ

Claude Code または CLI エージェントから Playwright テストを実行する場合は、冗長な出力でコンテキストウィンドウを消費しないよう、常に最小限のレポーターを使用してください。

CLI でテストを実行する場合は、--reporter=line または --reporter=dot を使用してください。 CI または CLAUDE 環境変数が設定されている場合、最小限のレポーターがデフォルトになるように playwright.config.ts を設定してください。設定例については playwright-patterns.md を参照してください。

ロケーターの優先順位（耐障害性の高い順）

ユーザーに表示される属性を常に優先してください。

1. page.getByRole('button', { name: 'Submit' }) — アクセシビリティロール
2. page.getByLabel('Email') — フォームコントロールのラベル
3. page.getByPlaceholder('Search...') — 入力欄のプレースホルダー
4. page.getByText('Welcome') — 表示テキスト（非インタラクティブ）
5. page.getByAltText('Logo') — 画像の代替テキスト
6. page.getByTitle('Settings') — タイトル属性
7. page.getByTestId('submit-btn') — 明示的なテスト契約
8. CSS/XPath — 最終手段として使用し、避けてください

基本ルール

• Web ファーストのアサーション：常に await expect(locator).toBeVisible() を使用してください。expect(await locator.isVisible()).toBe(true) は使用しないでください。Web ファーストのマッチャーは自動的に待機して再試行します。
• テストの分離：各テストで独自のデータを作成し、テスト間で状態を共有しないでください。
• 認証状態の再利用：セットアッププロジェクトと storageState を使って認証済み状態を保存してください。各テストで UI からログインしないでください。
• beforeEach よりフィクスチャ：フィクスチャはセットアップとティアダウンをカプセル化し、必要に応じて実行され、組み合わせることができます。

アンチパターン

• page.waitForTimeout(ms) — 代わりに自動待機するロケーターを使用してください
• page.locator('.class') — 代わりにロール／ラベル／testid を使用してください
• XPath セレクター — 壊れやすいため、ユーザーに表示される属性を使用してください
• テスト間で状態を共有する — 各テストで独自のデータを作成してください
• 各テストで UI ログインする — セットアッププロジェクトと storageState を使用してください
• await を使わない手動アサーション — Web ファーストのアサーションを使用してください
• ハードコードされた待機 — Playwright の自動待機に任せてください
• CI／エージェントでデフォルトのレポーターを使用する — --reporter=line または --reporter=dot を使用してください

チェックリスト

• ロケーターには CSS クラスや XPath ではなく、ロール／ラベル／testid を使用する
• すべてのアサーションで await expect() の Web ファーストマッチャーを使用する
• ページオブジェクトのロケーターをコンストラクターで定義する
• page.waitForTimeout() を使用せず、自動待機を使用する
• テストを分離し、状態を共有しない
• セットアッププロジェクトを通じて認証状態を再利用する
• ナビゲーションの前にネットワークモックを設定する
• テストデータをテストごと、またはフィクスチャを通じて作成する
• 複雑なフローにはデバッグログを追加する
• CI／エージェントのコンテキストでは最小限のレポーター（line／dot）を使用する

ページオブジェクトモデル、フィクスチャ、ネットワークモック、設定例については playwright-patterns.md を参照してください。