playwright

Playwright + Next.js のテストに関するベストプラクティス

Next.js アプリケーションで Playwright を使うテストを包括的に最適化するガイドです。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 - 共通のセットアップにはフィクスチャを使用する
• 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 ファーストのアサーションを使用する
• wait-avoid-hard-waits - 固定時間の待機を避ける
• wait-network-idle - 複雑なページではネットワークアイドルを使用する
• wait-action-retries - 操作前の自動待機をアクションに任せる
• wait-soft-assertions - 重要度の低い確認にはソフトアサーションを使用する
• wait-custom-timeout - タイムアウトを適切に設定する

4. 認証と状態（HIGH）

• auth-storage-state - ストレージ状態を使って認証を再利用する
• auth-multiple-roles - 役割ごとに個別のストレージ状態を使用する
• auth-session-storage - 認証でのセッションストレージを扱う
• auth-api-login - 認証のセットアップを高速化するために API ログインを使用する
• auth-parallel-workers - 並列テストにはワーカー単位の認証を使用する

5. モックとネットワーク（中〜高）

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

6. Next.js の統合（中）

• next-wait-hydration - 操作を開始する前にハイドレーションを待機します
• next-server-components - サーバーコンポーネントを正しくテストします
• next-app-router-navigation - App Router のナビゲーションパターンをテストします
• next-server-actions - サーバーアクションをエンドツーエンドでテストします
• next-baseurl-config - スムーズなナビゲーションのために baseURL を設定します

7. パフォーマンスと速度（中）

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

8. デバッグと CI（低〜中）

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

使用方法

詳しい説明とコード例については、各リファレンスファイルをお読みください。

• セクションの定義 - カテゴリーの構成と影響度
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
AGENTS.md	すべてのルールをまとめた完全なガイド
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報