fix

失敗するテスト、または不安定なテストを修正する

体系的な分類に基づいて、失敗する、または断続的に成功する Playwright テストを診断して修正します。

入力

$ARGUMENTS には以下が含まれます。

• テストファイルのパス：e2e/login.spec.ts
• テスト名："should redirect after login"
• 説明："checkout テストが CI では失敗するが、ローカルでは成功する"

手順

1. 失敗を再現する

エラーを記録するため、テストを実行します。

npx playwright test <file> --reporter=list

テストが成功する場合は、不安定な可能性があります。バーンインを実行します。

npx playwright test <file> --repeat-each=10 --reporter=list

それでも成功する場合は、並列ワーカーを使って試します。

npx playwright test --fully-parallel --workers=4 --repeat-each=5

2. トレースを取得する

完全なトレースを有効にして実行します。

npx playwright test <file> --trace=on --retries=0

トレースの出力を読み取ります。利用できる場合は、/debug を使ってトレースファイルを分析します。

3. 失敗を分類する

このスキルのディレクトリから flaky-taxonomy.md を読み込みます。

失敗するテストは、次の4つのカテゴリのいずれかに該当します。

カテゴリ	症状	診断
タイミング／非同期処理	どの環境でも断続的に失敗する	--repeat-each=20 でローカルに再現する
テストの分離	テストスイートでは失敗するが、単独では成功する	--workers=1 --grep "test name" では成功する
環境	CI では失敗するが、ローカルでは成功する	CI とローカルのスクリーンショット／トレースを比較する
インフラストラクチャ	ランダムに発生し、パターンがない	エラーにブラウザー内部への言及がある

4. 的を絞った修正を適用する

タイミング／非同期処理：

• waitForTimeout() を web-first アサーションに置き換える
• Playwright の呼び出しに不足している await を追加する
• アサーションの前に、特定のネットワーク応答を待つ
• 要素を操作する前に toBeVisible() を使う

テストの分離：

• テスト間で共有される可変状態を取り除く
• API またはフィクスチャを使って、テストごとにテストデータを作成する
• テストデータには一意の識別子（タイムスタンプ、ランダムな文字列）を使う
• データベースの状態が漏れていないか確認する

環境：

• ローカルと CI のビューポートサイズを一致させる
• スクリーンショットにおけるフォントのレンダリング差異を考慮する
• CI 環境に合わせるため、ローカルで docker を使う
• タイムゾーンに依存するアサーションを確認する

インフラストラクチャ：

• CI の実行環境が遅い場合はタイムアウトを延長する
• CI 設定にリトライを追加する（retries: 2）
• ブラウザーの OOM を確認する（並列ワーカー数を減らす）
• ブラウザーの依存関係がインストールされていることを確認する

5. 修正を検証する

安定性を確認するため、テストを10回実行します。

npx playwright test <file> --repeat-each=10 --reporter=list

10回すべて成功する必要があります。1回でも失敗した場合は、手順3に戻ります。

6. 再発を防止する

以下を提案します。

• 未設定の場合は、retries: 2 を指定して CI に追加する
• 設定で trace: 'on-first-retry' を有効にする
• 修正パターンをプロジェクトのテスト規約ドキュメントに追加する

出力

• 根本原因のカテゴリと具体的な問題
• 適用した修正（差分を含む）
• 検証結果（10回中10回成功）
• 再発防止の推奨事項