absolute-deflake

🧪 の絵文字で最初の応答を始めてください。

Absolute Deflake

成功と失敗が非決定的に入れ替わるテストを見つけ、それぞれの根本原因を診断して修正します。再試行やスキップではなく、非決定性の原因を取り除いてください。 出力は、テストごとの失敗率という証拠 → 原因 → 修正の順に示し、繰り返し実行して検証します。

references/health-engine.md の共有エンジンを実行します。DETECT → SCAN → TRIAGE → FIX → VERIFY → REPORT のループと安全性に関する契約については、そちらを読んでください。このファイルでは、不安定なテストに固有の内容のみを扱います。

---

使用する場面

• 「CI が不安定です」「このテストはランダムに失敗します」「断続的な失敗を修正してください」。
• ローカルでは成功するのに CI では失敗する（またはその逆）、あるいは N 回に約 1 回失敗するテスト。
• 実際の不安定さを覆い隠す retry／skip の注釈が付いたテストのバックログを解消する場合。

決定論的に失敗するテストには使いません。それは実際のバグまたはリグレッションです（修正には /absolute work を使うか、そのまま修正してください）。deflake の対象は非決定的な失敗です。

---

スキャン対象

不安定さは経験的に確認してください。誰かがそう言っただけで、テストが不安定だと決めつけてはいけません。繰り返し実行する回数 N のデフォルト値には、設定の preferences.health.deflakeRuns を使います（設定がない場合は 20）。

エコシステム	繰り返し実行／検出
Jest/Vitest	スイートを N 回実行（--run ループ）、実行順をランダム化（--shuffle／testSequencer）
pytest	pytest-randomly と pytest --count=N（pytest-repeat）；A/B テストでは -p no:randomly
Go	go test -count=N -shuffle=on ./...、-race

さらに、既存の retry／flaky／skip 注釈や、参照可能な場合は CI の履歴から兆候を探します。また、テストスイートを単独と全体／並列の両方で実行します。実行順や並行性に依存する失敗は、どちらか一方の実行方法でしか現れないことがあるためです。疑わしいテストごとに失敗率を記録してください。

---

よくある根本原因（推測せず診断する）

原因	手掛かり	修正
テスト順序／共有状態	単独では成功するが、スイートでは失敗する（またはその逆）	状態を分離する。テスト間でリセット／ティアダウンする
時刻／クロック	深夜、夏時間、または高負荷時に失敗する	フェイクタイマーを使う／クロックを注入する。実際の sleep は使わない
非同期処理の競合／await の欠落	並列実行時や CI の低速時に失敗する	実際の条件を await する。固定タイムアウトは使わない
ランダム性	パターンがなく、約 X％の割合で失敗する	RNG にシードを設定する。テストではシードを固定する
ネットワーク／外部 I/O	オフライン時や回線が遅いと失敗する	境界をモック／スタブに置き換える
順序が保証されないコレクション	map／set の反復順序により失敗する	アサーション前にソートする
リソースリーク／ポートの再利用	繰り返し実行時や並列実行時に失敗する	リソースを一意にし、クリーンアップする

---

リスクのランク付け（TRIAGE）

Wave	分類	デフォルト
1	原因が明確で、影響範囲が限定的（シード、await、フェイククロック、ソート）	すぐに修正
2	共有状態／順序に起因し、フィクスチャーのリファクタリングが必要	今回の作業でテストごとに修正
3	単なるテストの問題ではなく、実際の製品コードの競合を示す不安定さ	ゲート対象として表面化させる。コードで修正すべき本物のバグの可能性がある

不安定なテストが示しているのは、テストではなくコードの競合である場合があります。実際の並行処理のバグを隠すような「安定化」はしないでください。Wave 3 のケースには、実際の修正が必要であることを明示してください。

---

修正と検証

• 原因を修正します。その後、テストを何度も再実行して証明してください（順序をシャッフルし、並列で、-race を付けて実行します）。一度成功しただけでは不安定さを解消したとは言えません。ランダム化した N 回の実行を通じて成功する必要があります。
• 原因を修正したら、それを覆い隠していた retry／skip／flaky の注釈を削除します。
• 再試行の追加、タイムアウトのやみくもな延長、sleep の追加、テストのスキップによって「修正」することは絶対にしないでください。それでは不安定さを隠すだけで、取り除けません。
• 修正によって周辺のテストが不安定になっていないことを確認するため、テストスイート全体を再実行してください。

---

注意点

1. 修正として再試行／スキップする。 不安定さを覆い隠し、非決定性をそのままリリースしてしまいます。ここでは禁止です。
2. 競合状態を避けるために sleep する。 テストスイートの実行が遅くなるうえ、負荷がかかると依然として不安定になります。条件を待機してください。
3. 1回の成功で完了とする。 不安定なテストは確率的に失敗するため、ランダム化して何度も実行し、検証してください。
4. 実際に発生しているプロダクトの競合状態を安定化する。 コードに競合がある場合は、アサーションだけでなくコードを修正してください。
5. 実行順序や並列実行の観点を無視する。 単独実行とテストスイート内での実行の両方を行ってください。省略したほうにバグが潜んでいます。

---

関連コマンド

• /absolute upgrade — テストスイートが不安定だとアップグレードの検証が信頼できなくなるため、まず不安定さを解消してください。
• /absolute debt — 不安定なテストのアノテーションはテスト負債です。根本から解消します。
• /absolute work — 不安定さの原因が、設計上の対応を要する実際のプロダクトコードの競合状態である場合に使用します。