playwright

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

Next.js アプリケーションで Playwright を使用するための、包括的なテスト最適化ガイドです。信頼性が高く、高速で保守しやすい E2E テストを実現できるよう、影響度に基づいて優先順位付けした 8 カテゴリー、45 のルールをまとめています。

適用するタイミング

以下のような場合に、これらのガイドラインを参照してください。

• 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 は控えめに使用する
• loc-frame-locator - frameLocator で iframe 内の要素を特定する

3. 待機とアサーション（HIGH）

• wait-web-first-assertions - Web ファーストのアサーションを使用する
• assert-aria-snapshots - aria スナップショットでアクセシビリティ構造を検証する
• 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 連携用にレポーターを設定します

使用方法

まず、プロジェクトのルートで実行します。

npx -y @pymodel/react-frontend-skills detect                   # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill playwright  # deprecated APIs → rule IDs

該当する上記の各ルールと、scan で検出された項目について、references/<rule-id>.md を読み、重要な理由と、誤ったコードと正しいコードを確認します。