kao273183 flaky-test-hunter
⚙️ 執行前先讀
modules/config-loader.md。
為什麼需要這個 skill
Flaky test 是 CI 信任度殺手：
- 工程師看到紅燈第一反應是「應該又是 flaky，按 retry」
- 久了真實 bug 也被當 flaky 忽略
- 浪費 CI 時間（重跑成本）
- 工程師對自動化測試失去信心 → 開始 skip
→ 這個 skill 量化哪些測試在 flaky、給數據說服團隊修。
適用場景
- ✅ CI 有歷史紀錄（GitHub Actions / GitLab / CircleCI 至少跑 1 個月）
- ✅ 開始懷疑某些測試「隨機 fail」
- ✅ Release 前想清理 flaky 避免假警報
- ✅ 想把 flaky 自動移到 quarantine（隔離區）
不適用場景
- ❌ 沒 CI 歷史 / 剛起步 — 先累積數據
- ❌ 全部測試都 flaky — 系統性問題，不是個別 fix
- ❌ Manual test 不穩 — 跟程式碼 flaky 是不同問題
執行流程
Phase 1: 收集 CI 失敗紀錄
支援來源：
| CI 平台 | 取得方式 |
|---|---|
| GitHub Actions | gh run list --workflow=ci.yml --json + gh run view <id> |
| GitLab CI | glab ci list + GitLab API |
| CircleCI | CircleCI API |
| Jenkins | JUnit XML 直接讀 |
| pytest local | pytest --json-report 連續跑 N 次 |
預設讀過去 {{FLAKY_DAYS}} 天（預設 30 天）的紀錄。
Phase 2: 計算每個測試的 flakiness score
flakiness_score = (failures_in_passing_runs / total_runs) × 100%
Flakiness 定義：
- Stable: 0% flakiness（每次都 pass）
- Stable-fail: 失敗率 > 80% 且每次都 fail（真實 bug，不是 flaky）
- Flaky: 失敗率 1-80%（時 pass 時 fail）
只列出 Flaky 區間的測試。
Phase 3: 分類 flaky 嚴重度
| 分類 | Flakiness | 處理建議 |
|---|---|---|
| 🔴 High flaky | > 30% | 立刻 quarantine + 修 |
| 🟡 Medium flaky | 10-30% | 排程修，先進 quarantine |
| 🟢 Low flaky | 1-10% | 監控，看是否持續惡化 |
Phase 4: 識別 flaky 根因 pattern
掃描 flaky test 的程式碼，找常見問題：
| Pattern | 範例 | 修復方向 |
|---|---|---|
| Hard-coded sleep | Thread.sleep(2000) / await delay(2000) |
改 waitFor(condition) |
| 依賴時序 | expect(time.now() - start < 1000) |
改 deterministic time / clock injection |
| 共享狀態 | 全域 singleton 累積 | 每 test setUp/tearDown 重置 |
| 依賴外部網路 | call real API | Mock HTTP boundary |
| 隨機資料 | Math.random() 沒固定 seed |
固定 seed / faker.seed() |
| DB race condition | 平行測試讀寫同 row | 用 unique key / transaction |
| 動畫 / 過場 | cy.contains("Welcome") 但動畫沒完 |
cy.get(...).should("be.visible") |
| non-deterministic 順序 | expect(arr).toEqual([1,2,3]) 但實際 order 不定 |
用 arrayContaining |
| Memory / 資源洩漏 | 跑久了變慢 | 每 N test 重啟 worker |
Phase 5: 產出報告
寫到 ~/.local/share/qa-flaky/{repo}/report-{date}.md：
# Flaky Test Report · my-app · 2026-05-22
## 📊 整體
- 分析期間: 過去 30 天 (n=842 runs)
- 總測試數: 1247
- Stable: 1186 (95.1%)
- Flaky: 42 (3.4%)
- Stable-fail: 19 (真實 bug，不是 flaky)
**Flakiness Score**: 3.4% （目標 < 2%）
## 🔴 High flaky (> 30%)
### #1 `LoginUITests.testRetryAfterFailure` (Flakiness: 47%)
- 平台: iOS
- 失敗次數: 23 / 49 runs
- 最近失敗: 2026-05-21
- **疑似根因**: `Thread.sleep(2000)` (line 42) + 依賴後台 token expiry
- **建議修復**:
1. 改用 `expect(element).toExist()` 等待條件
2. 注入 fake clock，控制 token expiry
- **隔離**: 加 `@QuarantineFlaky` annotation，CI 標 warning 不阻擋
### #2 `WebSocketTest.testReconnect` (Flakiness: 35%)
- 平台: Backend
- ...
## 🟡 Medium flaky (10-30%)
[10 條...]
## 🟢 Low flaky (1-10%)
[30 條...]
## 📋 自動化處理建議
立刻動作:
- [ ] Quarantine 8 條 High flaky (PR: feature/quarantine-flaky)
- [ ] 建 8 個 JIRA ticket 追蹤修復（用 bug-report skill）
中期動作:
- [ ] 設 CI gate: flakiness > 30% 自動標 quarantine
- [ ] 把 Quarantine 區獨立成 nightly job，不阻 PR
## 📈 趨勢
- 上次報告 (2026-04): 5.1% flakiness
- 這次: 3.4% (-1.7% 改善 ✅)
Phase 6: 自動處理選項
互動式問使用者：
- 要不要對 High flaky 加
@Disabled/@QuarantineFlakyannotation？ - 要不要建 JIRA ticket（用
bug-reportskill）追蹤修復？ - 要不要產 PR 把 flaky 移到隔離區？
預設不主動修改測試碼，只給建議。
⚠️ 安全護欄
- ❌ 不主動 disable test（必使用者明確同意）
- ❌ 不對 stable-fail（真實 bug）標 flaky
- ✅ Quarantine 標記必含 "must-fix-by: YYYY-MM-DD" 避免被忘記
- ✅ 報告寫
~/.local/share/qa-flaky/，不污染 repo
設定依賴
| 設定 Key | 用途 | 缺值時行為 |
|---|---|---|
flaky_hunter.ci_platform |
CI 平台類型 | 偵測 .github/workflows/ 等推斷 |
flaky_hunter.lookback_days |
分析天數 | 預設 30 |
flaky_hunter.flaky_threshold |
標 flaky 起始失敗率 | 預設 1% |
flaky_hunter.high_flaky_threshold |
高嚴重度標準 | 預設 30% |
配套整合
持續看到 CI 不穩
↓
/flaky-test-hunter
↓ 報告找出 42 條 flaky
↓
互動式 → 對 8 條 High flaky 加 @Quarantine
↓
/bug-report → 為 8 條建 JIRA ticket
↓
修復後重跑 /flaky-test-hunter → 看 score 是否降
範例
詳見 examples.md