test-failure-investigator

テスト失敗の調査

テスト失敗を体系的に調査する、ランブック形式のスキルです。失敗したテストを受け取り、根本原因を特定して、対応を推奨します。

有効化

/test-failure-investigator [test-name-or-file]

調査フロー

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

テストを 3 回実行して、分類します。

結果のパターン	分類	対応
一貫して失敗する	リグレッション または 環境	ステップ 2 に進む
断続的に失敗する	フレーキー	ステップ 4 に進む
今回は成功する	一時的	CI のログと環境の差分を確認する

# Run test 3 times
for i in 1 2 3; do npx jest {{test_file}} 2>&1 | tail -5; echo "--- Run $i ---"; done

ステップ 2：範囲を絞り込む

# When did it start failing?
git log --oneline -20 -- {{related_source_files}}

# What changed recently?
git diff HEAD~5 -- {{related_source_files}}

# Does it fail in isolation?
npx jest {{test_file}} --testNamePattern="{{test_name}}"

# Does it fail with other tests?
npx jest --runInBand  # sequential execution

ステップ 3：根本原因を分析する

症状	考えられる原因	調査
タイムアウト	ネットワーク／DB 依存関係	外部サービスの稼働状況を確認する
アサーションの不一致	ロジックの変更	期待値と実際の値を比較し、git blame を確認する
インポートエラー	依存関係の変更	package.json の変更を確認し、npm ci を実行する
アクセス拒否	環境	ファイルのアクセス権と Docker ボリュームを確認する
メモリ不足	リソースリーク	--detectOpenHandles でプロファイルする

ステップ 4：フレークテストを調査する

# Run 10 times to confirm flakiness
for i in $(seq 1 10); do npx jest {{test_file}} --forceExit 2>&1 | grep -E 'PASS|FAIL'; done

# Common flaky causes:
# - Shared state between tests (missing cleanup)
# - Time-dependent assertions (use fake timers)
# - Race conditions (missing await)
# - Port conflicts (use random ports)
# - Order dependency (run with --randomize)

ステップ 5：報告する

## Test Failure Report
- **Test**: {{test_name}}
- **File**: {{test_file}}
- **Classification**: Regression / Flaky / Environment / Transient
- **Root Cause**: {{description}}
- **First Failed**: {{commit_hash}} ({{date}})
- **Fix**: {{recommended_action}}
- **Verified**: [ ] Fix applied and test passes 3x consecutively

組み合わせ

調査後、次のスキルと組み合わせます。

• /bug-reporting-excellence — リグレッションが見つかった場合、バグレポートを提出します
• /regression-testing — リグレッションの場合、リグレッションテストスイートに追加します
• /qe-test-execution — 修正後にテストを再実行します

注意点

• エージェントはテストを実行せずに根本原因を推測することがあります。必ず先に再現してください
• 「自分のマシンでは動く」は診断になりません。環境（node のバージョン、OS、依存関係）を比較してください
• 10 回中 9 回成功するフレークテストでも、CI では「成功」と報告されます。10 回以上実行してください
• テストの分離不備は、フレークテストの最大の原因です。beforeAll/afterAll で共有状態がないか確認してください