test-flakiness

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation

自動化モード：modes.automation を解決します（project.local.yaml → project.yaml → デフォルトの collaborative）。すべての AskUserQuestion 呼び出しと すべてのファイル書き込みは、.claude/docs/automation-modes.md に従います （collaborative は常に質問 · guided は主要なもののみ · autonomous は記録して続行； automation_always_ask カテゴリは常にプロンプトを表示）。

テストの不安定さの検出

不安定なテストとは、コードに変更がないにもかかわらず、成功したり失敗したりするテストです。不安定なテストは、ある意味ではテストがないよりも厄介です。チームが CI の失敗を無視するようになり、本当の失敗が見えにくくなるからです。このスキルでは、不安定なテストを特定し、考えられる原因を説明し、それぞれを隔離するか修正するかを提案します。

出力： tests/regression-suite.md の隔離セクションを更新 + 必要に応じて production/qa/flakiness-report-[date].md を作成

実行するタイミング：

• ポリッシュ段階（テストが何度も実行され、統計的な傾向を信頼できる場合）
• 開発者が CI の失敗を「たぶん不安定なだけ」と片付け始めたとき
• /regression-suite で診断が必要な隔離済みテストが見つかった後

---

1. 引数の解析

モード：

• /test-flakiness [ci-log-path] — 特定の CI 実行ログファイルを分析します
• /test-flakiness scan — .github/ または標準のログ出力ディレクトリにある、 利用可能なすべての CI ログをスキャンします
• /test-flakiness registry — 既存の regression-suite.md の隔離セクションを読み、 すでに把握している不安定なテストへの修正方針を提示します
• 引数なし — 自動検出します。CI ログにアクセスできる場合は scan を実行し、 できない場合は registry を実行します

---

2. CI ログデータの特定

オプション A — GitHub Actions（推奨）

テスト結果のアーティファクトを確認します：

ls -t .github/ 2>/dev/null
ls -t test-results/ 2>/dev/null

Godot プロジェクトの場合：GdUnit4 は、JUnit 形式と互換性のある XML 結果を、 reports/（デフォルトのレポートフォルダー、res://reports/）に出力します。 reports/ と、実行結果を保存した test-results/ に .xml ファイルがあるか確認します。

Unity プロジェクトの場合：game-ci テストランナーは、デフォルトで test-results/ に NUnit XML を出力します。

Unreal プロジェクトの場合：自動化ログは Saved/Logs/ に出力されます。 Result={Success} と Result={Fail} を grep します。各テストには Test Completed. Result={<status>} が出力されます （docs/engine-reference/unreal/current-best-practices.md、「コマンドライン」）。

オプション B — ローカルログファイル

パス引数が指定されている場合は、そのファイルを直接読み取ります。

オプション C — ログデータがない場合

ログが見つからない場合：

「CI ログデータが見つかりませんでした。不安定なテストを検出するには、 複数回実行したテスト結果の履歴が必要です。次の方法があります。

1. テストスイートを少なくとも 3 回実行し、出力ログを収集する
2. CI パイプラインの出力を確認し、ログを test-results/ に保存する
3. /test-flakiness registry を実行して、tests/regression-suite.md で すでに不安定としてフラグが付けられているテストを確認する」

停止して、どの方法で進めるかユーザーに尋ねます。

---

3. テスト結果の解析

見つかった CI ログまたは結果ファイルごとに、次の情報を解析します。

JUnit XML 形式（GdUnit4）：

• <testcase name= を grep してテスト名を取得します
• <failure または <error を grep して失敗を特定します
• classname および name 属性を解析し、完全なテスト識別子を取得します

NUnit XML 形式（Unity — <test-run> 要素を /smoke-check が読み取るファイル）：

• 各テストは <test-case 要素で、その fullname 属性が識別子です
• result 属性は Passed、Failed、Inconclusive、または Skipped です （docs/engine-reference/unity/current-best-practices.md、「コマンドライン」）。 履歴に含めるのは Passed と Failed のみです

プレーンテキストログ：

• 合格／失敗のパターンを grep します。
  • Godot：テスト名の近くにある PASSED / FAILED
  • Unreal：Result={Success} / Result={Fail}
  • Unity：Test passed / Test failed

表を作成します：test_id → [run1_result, run2_result, run3_result, ...]

---

4. 不安定なテストを特定する

テストは、コード変更がない状態で実行を重ねた際、結果履歴に PASS と FAIL の両方が記録されている場合、不安定です。

不安定さのしきい値：

• 不安定さが高い：実行の 25% 超で失敗 — 直ちに隔離します
• 不安定さが中程度：実行の 5〜25% で失敗 — 早急に調査して修正します
• 不安定さが低い／疑いあり：実行の 1〜5% で失敗 — 監視します。実際にまれな失敗である可能性もあります

実行回数が 3 回未満の場合、失敗率にかかわらず、すべての検出結果は 疑いあり です。 2 回の実行で 1 回失敗すると 50% に見えますが、データポイントは 1 つです。隔離せず、 疑いありと分類し、さらに実行データがあるか確認してください。 上記の段階と隔離は、実行回数が 3 回以上の場合に適用されます。

不安定なテストごとに、考えられる原因を分類します。

原因の分類

原因	症状	修正の方向性
タイミング／非同期処理	シグナルやタイマーを待機した後に失敗する。成功率がシステム負荷と相関する	明示的な await／同期処理を追加します。時間ベースの遅延は避けます
実行順序への依存	特定の他のテストの後に実行すると失敗するが、単独では成功する	適切なセットアップ／ティアダウンを追加します。テストを分離します
乱数シード	パターンなく断続的に失敗する。RNG を使用している	明示的なシードを渡します。テストで randf() を使用しないでください
リソースリーク	テスト実行の後半ほど失敗が増える	ティアダウンでクリーンアップを修正します。孤立したノード（Godot）やオブジェクトの破棄（Unity）を確認します
外部状態	前のテストで作成されたファイル、シーン、グローバルが存在すると失敗する	テストをファイルシステムから分離します。メモリ内モックを使用します
浮動小数点数	== 0.5 のような比較で失敗する	イプシロン比較（is_equal_approx、Assert.AreApproximately）を使用します
シーン／プレハブの読み込み競合	シーンの準備が完了する前に失敗する	インスタンス化後に 1 フレーム待機します。await get_tree().process_frame を使用します

Grep を使って、テストファイル内のタイミング呼び出し、randf、グローバル状態へのアクセス、 浮動小数点数の等価比較を確認し、原因を絞り込みます。

---

5. 対応を提案する

不安定なテストごとに：

隔離（不安定さが高い）：

「このテストを直ちに隔離してください。エンジン独自の仕組みでスキップし、 tests/regression-suite.md の隔離セクションに記録してから、隔離を解除する前に 根本原因を修正してください。」

エンジン別のスキップ方法 — プロジェクトで使用しているエンジンの項目のみを記載します：

• Godot（gdUnit4）、GDScript：テスト関数にスキップパラメーターを指定します — func test_x(_do_skip := true, _skip_reason := "flaky: [cause]")。gdUnit4 は addons/gdUnit4/src/core/GdUnitTestSuiteScanner.gd 内の引数名 do_skip と skip_reason を読み取ります（先頭の _ は許可されます）。この仕様は gdUnit4 6.2.2 時点のものです。 インストールされているバージョンで確認してください。
• Godot（gdUnit4）、C#：根拠を確認できません — gdUnit4 の C# テスト属性は addons/gdUnit4/ のソースに含まれておらず、docs/engine-reference/godot/ にも 記載がありません。隔離セクションに記録し、C# テストをどのようにスキップしているか ユーザーに確認してください。属性を捏造しないでください。
• Unity（NUnit）：[Ignore("flaky: [cause]")] — NUnit 3 では理由の指定が必要です
• Unreal：根拠を確認できません — docs/engine-reference/unreal/ に自動化テストを スキップする方法の記載はありません。隔離セクションに記録し、CI でテストをどのように 除外しているかユーザーに確認してください。フラグを捏造しないでください。

早急に調査して修正（中程度）：

「このテストは断続的に不安定です。根本原因は [cause] と考えられます。 修正案：[原因の分類に基づく具体的な修正案]。まだ隔離せず、 テストを直接修正してください。」

監視（低／疑いあり）：

「このテストには不安定さの疑いがあります。隔離する前に さらに実行データを収集してください。回帰テストスイートに「疑いあり」として記録してください。」

---

6. レポートを生成する

会話内の概要

## Flakiness Detection Results

**Runs analysed**: [N]
**Tests tracked**: [N]

### Flaky Tests Found

| Test | System | Fail Rate | Confidence | Likely Cause | Recommendation |
|------|--------|-----------|------------|--------------|----------------|
| [test_name] | [system] | [N]% | confirmed | Timing | Quarantine + fix async |
| [test_name] | [system] | [N]% | confirmed | Float comparison | Fix: use epsilon compare |
| [test_name] | [system] | [N]% | suspected (fewer than 3 runs) | Order dependency | Collect more runs before acting |

### Clean Tests (no flakiness detected)

[N] tests ran across [N] runs with consistent results — no flakiness detected.

### Data Limitations

[Note if fewer than 5 runs were available — fewer runs = less statistical confidence]

---

7. 回帰スイートの更新とレポートファイルの任意作成

「見つかった不安定なテストを、tests/regression-suite.md の隔離セクションに追加してもよろしいですか？」

承認された場合は、Edit を使って隔離対象テストの表に項目を追加します。 既存の隔離対象項目は決して削除せず、新しい項目のみ追加してください。

別途、次のように確認します：「詳細な不安定性レポートを production/qa/flakiness-report-[date].md に書き込んでもよろしいですか？」

詳細なレポートには、原因の詳細とエンジン固有の修正例を含む、テストごとの分析を記載します。

書き込み後：

• 隔離対象の各テストについて：「CI でこのテストを無効化するため、エンジン固有のスキップ注釈を追加してください。根本原因を修正した後に再度有効化してください。」
• 修正可能なテストについて：「[test] の修正は簡単です。行 [N] の等価比較を is_equal_approx を使うように変更してください。」
• 要約：「すべての隔離注釈を適用すれば、CI はグリーンになるはずです。リリースゲートまでに、隔離対象の [N] 件のテストの修正作業を予定してください。」

---

共同作業のプロトコル

• テストファイルは決して削除しない — 隔離とは注釈の追加と一覧への記載であり、削除ではありません
• 統計的な信頼性が重要 — 実行回数が 3 回未満の場合は、調査結果を「確認済み」ではなく「疑いあり」として示し、追加の実行データがあるか確認してください
• 常に修正を目指す — 隔離は一時的な措置です。隔離を推奨する場合でも、修正の方向性を示してください
• 書き込み前に確認する — 回帰スイートの更新にもレポートファイルの作成にも、明示的な承認が必要です。書き込み時：Verdict: COMPLETE — 不安定性レポートを書き込みました。拒否された場合：Verdict: BLOCKED — ユーザーが書き込みを拒否しました。
• CI での不安定さはチームの課題です — 一覧と推奨アクションを明確に示してください。チームに知らせず、黙って隔離するだけにしてはいけません