debug-fix-failed-flaky-autotests

失敗する自動テストのデバッグと修正

失敗する自動テストを診断し、的を絞って修正します。 4 つのステップを順番に実行します。 詳細な修正方法とコード例：references/DEBUGGING_QUICK_REFERENCE.md。

ステップ 1：失敗を分析する

• フレームワークを特定します。使用するデバッグツールはフレームワークによって異なります。
  • Playwright：CLI デバッグ、トレースビューアー、MCP スナップショット。
  • CodeceptJS：--steps モード、CDP 検査。
  • Cypress：devTools、失敗時のスクリーンショット。
  • WebdriverIO：Selenium ログ。
• エラーを分類します。
  • ロケーター（要素がない、またはアクセスできない）。
  • タイミング（タイムアウト／競合状態）。
  • アサーション（期待値 ≠ 実際の値）。
  • フロー（ナビゲーション、前提条件）。
  • インフラストラクチャ（CI／ブラウザー／ネットワーク）。
• 最後に、根本原因と修正カテゴリからなる仮説を提示します。

ステップ 2：調査して診断する

• DOM の検査：
  • Playwright：page.locator('selector').evaluate(el => el.outerHTML)。
  • CodeceptJS：I.executeScript(() => document.querySelector('.selector').outerHTML)。
  • MCP スナップショット：複雑な要素のライブ DOM 状態を取得します。
• コンソールログとネットワークログ：
  • コンソール：page.on('console', msg => console.log(msg.text()))。
  • 失敗したリクエスト：page.on('requestfailed', r => console.log(r.failure().errorText))。
• トレース分析（Playwright）：npx playwright show-trace trace.zip。
  • クリック、ナビゲーション、ネットワークリクエストのタイミングと順序を調べます。

ステップ 3：修正する

次の優先順位で修正します：ロケーター → タイミング → アサーション → フロー。

• ロケーター：安定したセレクターを使用します（data-testid → aria-label → role → id → text → CSS/XPath）。
  • 古くなった要素を再取得し、非表示の要素をスクロールして表示し、複数の一致がある場合は .first() を使用します。
• タイミング：フレームワーク標準の待機機能を使用します（waitFor、waitForNavigation、waitForLoadState('networkidle')）。
  • sleep(5000) や wait(2) のような固定時間の待機は使用しないでください。
• アサーション：柔軟に照合できる contains／正規表現を使用します。
  • 想定ではなく、テスト仕様に照らして期待値を確認します。
• フロー：前提条件（ログイン、ナビゲーションの順序、テストデータ）が満たされていることを確認します。
  • 前回の実行からテスト状態を分離します。

各カテゴリの修正前／修正後の例：references/DEBUGGING_QUICK_REFERENCE.md。

ステップ 4：検証して安定化する

テストを再実行します。

npx playwright test path/to/test.spec.ts
npx codeceptjs run path/to/test.js

次の条件を満たすと、テストは安定していると判断できます。

• 2 回連続で成功する。
• 耐障害性の高いロケーターを使用している。
• 動的コンテンツを適切に待機している。

修復の試行は合計 3 回までです。 3 回失敗したら中止し、試した内容を記録して、ユーザーに指示を求めてください。

修正内容を記録します：根本原因、適用した修正、検証結果。

MCP デバッグツール（任意）

標準的な修正で解決しない場合、UI が複雑な場合（ドロップダウン、モーダル、動的コンテンツ）、またはライブ DOM の検査が必要な場合は、MCP を使用します。

• Playwright MCP：ライブスナップショット、要素数の確認、各アクション後の DOM 検査。
• CodeceptJS MCP：CDP ベースの検査、ライブデバッグ用の --steps モード。

ユーザーとのやり取り

不明な点がある場合は質問します。

❓ Which element should I target for this action?

Options:
1. Submit button (data-testid="submit")
2. Save button (aria-label="Save")
3. Other (specify)

進捗を報告します。

🔍 Analyzing failure...
  - Error: Element not found
  - Context: Login test, line 42

🔧 Applying fix...
  - Issue: Selector too broad
  - Fix: Using getByRole('button', { name: 'Login' })

✅ Test passed! (Run 1/2)