Playwright + Next.js テスティング ベストプラクティス

Playwright と Next.js アプリケーションのための包括的なテスト最適化ガイド。8 つのカテゴリに分類された 43 のルールを含み、信頼性が高く、高速で、保守しやすい E2E テストをガイドするため影響度順に優先付けされています。

使用するタイミング

以下の場合にこれらのガイドラインを参照してください：

• Next.js アプリケーション用の新しい Playwright テストを作成する場合
• 不安定な、または失敗するテストをデバッグする場合
• テスト実行速度を最適化する場合
• 認証状態の再利用をセットアップする場合
• テスト用の CI/CD パイプラインを構成する場合
• Server Components および App Router 機能をテストする場合
• テストコードを信頼性の問題で検証する場合

ルールカテゴリ（優先度別）

優先度	カテゴリ	影響度	プレフィックス
1	テストアーキテクチャ	CRITICAL	arch-
2	セレクタ & ロケータ	CRITICAL	loc-
3	待機 & アサーション	HIGH	wait-
4	認証 & 状態	HIGH	auth-
5	モッキング & ネットワーク	MEDIUM-HIGH	mock-
6	Next.js インテグレーション	MEDIUM	next-
7	パフォーマンス & 速度	MEDIUM	perf-
8	デバッグ & CI	LOW-MEDIUM	debug-

クイックリファレンス

1. テストアーキテクチャ (CRITICAL)

• arch-test-isolation - 各テストに新しいブラウザコンテキストを使用
• arch-parallel-execution - 並列テスト実行を有効化
• arch-page-object-model - 複雑なページに Page Object Model を使用
• arch-fixtures - 共有セットアップに fixtures を使用
• arch-test-production - プロダクションビルドに対してテストする
• arch-cleanup-state - 各テスト後にテスト状態をクリーンアップ

2. セレクタ & ロケータ (CRITICAL)

• loc-role-selectors - CSS ではなくロールベースセレクタを使用
• loc-data-testid - 動的要素に data-testid を使用
• loc-label-selectors - フォーム入力に getByLabel を使用
• loc-text-selectors - 静的コンテンツに getByText を使用
• loc-avoid-xpath - XPath セレクタを避ける
• loc-chained-locators - 詳細度のためにロケータをチェーンする
• loc-placeholder-selector - getByPlaceholder は控えめに使用

3. 待機 & アサーション (HIGH)

• wait-web-first-assertions - web-first アサーションを使用
• wait-avoid-hard-waits - ハードウェイトを避ける
• wait-network-idle - 複雑なページにはネットワークアイドル状態を使用
• wait-action-retries - アクションが相互作用前に自動的に待機するようにする
• wait-soft-assertions - 重要でないチェックには soft assertions を使用
• wait-custom-timeout - タイムアウトを適切に設定

4. 認証 & 状態 (HIGH)

• auth-storage-state - ストレージ状態を使用して認証を再利用
• auth-multiple-roles - 異なるロールに対して別々のストレージ状態を使用
• auth-session-storage - 認証のためにセッションストレージを処理
• auth-api-login - より高速な認証セットアップに API ログインを使用
• auth-parallel-workers - 並列テストに worker スコープの認証を使用

5. モッキング & ネットワーク (MEDIUM-HIGH)

• mock-api-responses - 決定論的テスト用に API レスポンスをモック
• mock-intercept-modify - 実際のレスポンスをインターセプトして変更
• mock-har-files - 複雑なモックシナリオに HAR ファイルを使用
• mock-abort-requests - 不要なリクエストを中止
• mock-network-conditions - ネットワーク状態をシミュレート

6. Next.js インテグレーション (MEDIUM)

• next-wait-hydration - 相互作用前にハイドレーション完了を待機
• next-server-components - Server Components を正しくテスト
• next-app-router-navigation - App Router ナビゲーションパターンをテスト
• next-server-actions - Server Actions をエンドツーエンドでテスト
• next-baseurl-config - クリーンなナビゲーション用に baseURL を設定

7. パフォーマンス & 速度 (MEDIUM)

• perf-sharding - 大規模なテストスイートにはシャーディングを使用
• perf-headless-ci - CI ではヘッドレスモードを使用
• perf-browser-selection - ブラウザを戦略的に選択
• perf-reuse-server - 可能な場合は開発サーバーを再利用
• perf-retries - 不安定なテスト回復用にリトライを設定

8. デバッグ & CI (LOW-MEDIUM)

• debug-trace-viewer - 失敗したテストに trace viewer を使用
• debug-screenshots-videos - 失敗時にスクリーンショットと動画をキャプチャ
• debug-inspector - インタラクティブなデバッグに Playwright Inspector を使用
• debug-ci-reporters - CI インテグレーション用にレポータを設定

使用方法

詳細な説明とコード例については、個別のリファレンスファイルを参照してください：

• Section definitions - カテゴリ構造と影響度レベル
• Rule template - 新しいルール追加用テンプレート

リファレンスファイル

ファイル	説明
AGENTS.md	すべてのルールを含む完全コンパイルガイド
references/_sections.md	カテゴリ定義と順序付け
assets/templates/_template.md	新しいルール追加用テンプレート
metadata.json	バージョンおよびリファレンス情報