四類根因

計時依賴

Test 依賴特定的時間條件 — timeout、delay、animation duration。系統負載不同時，時間條件可能滿足也可能不滿足。

常見模式：

• await Future.delayed(Duration(seconds: 2)) + assertion — 如果操作在 2 秒內完成，test 通過；如果 CI 機器負載高導致操作超過 2 秒，test 失敗
• expect(stopwatch.elapsed, lessThan(Duration(seconds: 1))) — 效能斷言在不同機器上結果不同

處理策略：用事件驅動代替 timeout。等待 stream.first 代替 delay(2s) + check；用 completion signal 代替固定等待時間。如果必須用 timeout，設定寬裕的上限（10x 預期時間）而非精確的預期值。

環境差異

Test 在不同環境下行為不同 — 作業系統、檔案系統、時區、locale、DNS 解析。

常見模式：

• 檔案路徑分隔符（/ vs \）在不同 OS 下不同
• 時間格式化結果依時區而定（UTC vs local）
• 浮點數比較因 CPU 架構不同有微小差異

處理策略：用 path.join 代替硬編碼路徑；時間操作用 UTC；浮點比較用 closeTo 代替精確比較。在 CI 中固定環境變數（TZ=UTC、LANG=en_US.UTF-8）。

資源競爭

Test 依賴共享資源（port、暫存檔、資料庫行）— 平行執行時多個 test 同時存取同一資源，結果依賴執行順序。

常見模式：

• 多個 test 監聽同一個 port — 第二個綁定失敗
• 多個 test 寫入同一個暫存檔 — 內容被覆蓋
• 多個 test 操作同一個資料庫 table — 資料互相干擾

處理策略：每個 test 使用獨立的資源（隨機 port、唯一檔名、隔離的資料庫 schema）。如果資源無法隔離，sequential 執行相關 test（@sequential 標註）。

非確定性輸出

程式碼的輸出本身不確定 — Set 的迭代順序、Map 的 key 順序、非同步操作的完成順序。

常見模式：

• 斷言 Set 的 toString() 結果等於特定字串 — Set 的迭代順序不保證
• 斷言 Future.wait([a, b]).then((results) => results[0]) — a 和 b 的完成順序不固定
• 斷言 JSON 序列化的 key 順序 — Map 的 key 順序在不同實作中不同

處理策略：不斷言順序（用 containsAll 代替 equals 比較集合）；不斷言序列化格式（反序列化後比較值）；用 completion matcher 代替順序假設。

診斷步驟

發現疑似 flaky test 時的診斷步驟：

1. 確認 flaky：在乾淨環境連續跑 20 次，確認失敗是隨機的（如果每次都失敗，是 bug 不是 flaky）
2. 收集失敗訊息：記錄每次失敗的 assertion 訊息、stack trace、環境資訊（OS 版本、CI 機器 ID）
3. 分類：失敗訊息指向時間（timeout）→ 計時依賴；指向值不同 → 非確定性或環境差異；指向連接失敗 → 資源競爭
4. 修復：根據分類使用對應的處理策略

分類和修復之外，flaky test 的根因有時來自 assertion 本身的設計 — Assertion 品質三問提供判斷 assertion 是否有效的框架。如果 flaky 的根因是 mock 和真實服務的行為差異，回到 Mock 邊界判斷決策表判斷 mock 是否還適用。Protocol integration test 在 CI 中的服務 fixture 管理也是 flaky 的常見來源 — 服務啟動不完全就開始跑 test。

對應 findings

待寫章節

• Mock 邊界判斷決策表（什麼時候 mock 夠、什麼時候需要 real）
• Test data 代表性（手寫 vs 錄製 vs 生成）
• Assertion 品質三問（斷言的是行為嗎？能區分正確和錯誤嗎？會 flaky 嗎？）
• Flaky test 根因分類（計時依賴 / 環境差異 / 資源競爭 / 非確定性）

跨分類引用

• → monitoring 模組五 平台適配：各平台的 error 攔截機制差異影響 test 設計

概念位置

Flaky Test 位在 test stage 與 release gate 之間，會放大重跑成本與判讀延遲。

可觀察訊號

• 同一 commit 重跑結果時好時壞。
• 失敗集中在等待條件、時間假設或外部依賴。
• 團隊習慣以重跑代替根因修復。

接近真實服務的例子

UI 測試在動畫未完成時抓取元素，或整合測試依賴不穩定第三方 API，都容易出現 flaky pattern。

設計責任

Flaky Test 治理要建立 owner、隔離策略、修復 SLA 與觀測指標，讓測試結果恢復可判讀性。

這個詞出現在「測試紅燈不一定是真的壞」這個問題裡。

flaky test（不穩定測試）指同一份程式碼、同一個測試，什麼都沒改，卻有時過有時不過。

它是測試領域的 false positive——測試報紅、但被測的程式碼其實沒問題——而 flaky 特指其中「間歇、非確定性」的那種。

常見成因

• 競態（race condition）、依賴執行順序。
• 時間依賴：sleep、timeout、時鐘、時區。
• 共用狀態沒清乾淨：測試之間互相污染。
• 外部依賴：網路、第三方服務的暫態抖動。

為何危險

flaky 會侵蝕對測試套件的信任：紅了第一反應是點重跑而不是查 bug，久了連真的失敗也被當 flaky 忽略——這是測試版的 alert fatigue。

與 spurious failure 的區別

flaky 強調「間歇重現」（重跑可能就過）；spurious failure 強調「這次失敗的原因不是被測對象」，不一定間歇。兩者都是測試的 false positive，角度不同。

相關概念

• 上位概念：false positive。
• 近鄰：spurious failure、後果 alert fatigue。

事故類型：cross-file 狀態污染、dart test runner 同 process 共用 GetX 症狀：flutter test 約 50% 機率隨機失敗、每次失敗的 test 不固定；單獨跑該 test file 100% 通過 根因：dart test runner 在同 process 內跑多個 test file 共用 GetX 容器；前面 file 的 setUp 留下殘留（測試 mode 旗標、未 dispose 的 controller、stream subscription）污染後面 file 的測試環境

事故場景

表面症狀

跑 flutter test 全 suite，Run 1 fail、Run 2 pass、Run 3 pass、Run 4 fail、Run 5 fail。看到的失敗訊息類似：

100:27 +125: PrintCenter 廚房印表機管理 kitchenPrinter 向後兼容取第一台 - did not complete [E]
200:27 +125: PrintCenter 廚房印表機管理 重複呼叫 initFakeKitchenPrinters 會清除舊的 - did not complete [E]
300:27 +125: Some tests failed.

訊息直接點名 PrintCenter 廚房印表機管理 group 的兩個 test「did not complete」。直覺反應：那兩個 test 有問題、去看那個 file。

第一次診斷與失敗的修法

打開 online_order_print_handler_test.dart，看到 PrintCenter 廚房印表機管理 group 的 setUp 沒做 Get.reset()、純粹依賴 outer setUp 的 Get.reset()。判斷可能是 outer setUp 的 OnlineOrderPrintHandler.onInit 在這個 group 留下副作用（stream subscription 之類），於是給這個 group 加自己的 reset：

 1group('PrintCenter 廚房印表機管理', () {
 2  late PrintCenter printCenter;
 3
 4  setUp(() {
 5    Get.reset();  // ← 加這行隔離 outer setUp 的副作用
 6    printCenter = PrintCenter(FakePrinterAdapter('main'));
 7    Get.put(printCenter);
 8  });
 9
10  tearDown(() {
11    Get.reset();  // ← 加這行確保不殘留
12  });
13});

跑 5 次：Run 1 fail、Run 2 pass、Run 3 pass、Run 4 fail、Run 5 fail——flakiness 比例沒改變。

修錯了。

重新診斷：看 +N -1 計數的真正位置

把 fail 輸出存進檔案、仔細看 progress line 的 +N -1 部分：

100:08 +125 -1: ... auto_service_config_test.dart: ...
200:08 +126 -1: ... settle_page_order_object_test.dart: SettlePage.orderObject reactivity searchedOrder 變更：badge 立即更新（list 與 selected 都沒命中時）
300:08 +127 -1: ... auto_service_config_test.dart: ...

-1 在第 126 個 test 才第一次出現——失敗的不是 print handler，是中間夾的 widget test。再看另一次 fail：

100:09 +124 -1: ... settle_page_order_object_test.dart: SettlePage.orderObject reactivity orderList[i] 替換：badge 從「已完成」立即變「退貨」

不同 run 失敗的 test 不一樣，但都是 settle_page_order_object_test.dart 的不同 case。print handler 的 did not complete 是被牽連、不是源頭。

確認 root cause：單獨跑全綠

把 widget test 單獨重複跑 8 次：

1for i in 1 2 3 4 5 6 7 8; do
2  flutter test test/widgets/settle_page_order_object_test.dart 2>&1 | tail -1
3done

8/8 全綠。單獨跑沒問題、混進全 suite 跑就 flaky——這是 cross-file pollution 的固定特徵。

為什麼 did not complete 訊息會誤導

dart test runner 的失敗訊息設計上有個盲點：

• +N 是累計通過數
• -N 是累計失敗數
• did not complete 是某個 test 還沒跑完整體就終止了（process 退出 / 超時 / 前面有未捕捉錯誤導致 runner 提前結束）

當前面有 test 失敗、後面的 test 沒機會跑、這些後面的 test 會印 did not complete——但它們本身沒問題。看到 did not complete 直覺會想「這個 test 卡住了」、但真實意思更接近「這個 test 還沒跑、上游已掛」。

正確的診斷流程：

1. 找 -N 第一次出現的位置（-1 表示第一個失敗）
2. 對照那一行的 test 名稱、那才是真正失敗的源頭
3. did not complete 出現的 test 通常只是受牽連

我第一次掉的坑：直接讀 did not complete 的 test 名、跳過了「往前找 -1 第一次出現」這步。

為什麼 cross-file 會污染：dart test runner 與 GetX 的不對齊

dart test runner 的執行模型

flutter test（背後是 dart test）跑全 suite 時不一定 1 file = 1 isolate。預設行為：

• 多個 test file 可能共用同一個 isolate / Dart VM
• 共用 isolate 等於共用所有 process-scoped state（static field、singleton、未 GC 的全域物件）

並發策略受 --concurrency 與 platform 影響、行為不固定，但「共用 process」是日常常見現象。

GetX 的 state 是 process-scoped

GetX 的 Get.put / Get.find 把 instance 放進一個 process-global 容器。Get.reset() 清空容器、但有些東西不會被 reset：

• Get.testMode 是 static field、reset() 不動它
• 如果 instance 在 onInit 內 subscribe 了 stream（例如 BroadcastReceiveService.messages.listen）、Get.reset() 移除 instance reference 但 subscription 不會自動 cancel
• StreamController / Timer / Future.delayed 在 GetX 容器外仍然活著

實際發生的污染鏈

跑全 suite 時，假設執行順序是：

11. test/services/online_order/...      ← 最前面
22. test/widgets/settle_page_order_...   ← 中間
33. test/services/auth_service_config... ← 後面

第 1 個 file 的 setUp 若有 Get.put(SomeService())，service 在 onInit 內訂閱了 stream，就算 tearDown 跑了 Get.reset()、那條 stream subscription 仍 active。第 2 個 file 開始跑時：

• 它的 setUp 也呼叫 Get.put(...)、放進去的物件可能是 完全不同類型 ——但 GetX 容器內可能還有上一輪殘留的物件
• 第 2 個 file 的 widget test 進入 widget tree、Obx 訂閱、各種 reactive 路徑啟動
• 上一輪殘留的 stream / timer 此時 fire、進到不該觸及的 state

整個 race 在「殘留事件何時 fire vs widget test 何時 expect」之間，所以 flakiness 是 ~50% 而不是 100%。

解法：setUp 開頭主動 reset

對任何用 GetX 的 test，setUp 最開頭就該 reset、不要依賴上一個 file 的 tearDown 跑乾淨：

 1setUp(() {
 2  // 同 process 內跑全 suite 時其他 test file 可能在 GetX 容器留殘留
 3  // （Get.testMode、未 dispose 的 controller、未 cancel 的 stream subscription），
 4  // setUp 開頭主動 reset 切斷 cross-file 污染
 5  Get.reset();
 6  Get.testMode = true;
 7  // ... 之後再 Get.put 自己需要的東西
 8});
 9
10tearDown(() {
11  Get.reset();
12});

把這個 pattern 加到所有 widget test 與 controller test 的 setUp 之後，全 suite 連跑 5 次：

1Run 1: All tests passed!
2Run 2: All tests passed!
3Run 3: All tests passed!
4Run 4: All tests passed!
5Run 5: All tests passed!

5/5 全綠，flakiness 消失。

為什麼 tearDown 的 reset 不夠

理論上 tearDown 已經 Get.reset() 了，下個 test 的 setUp 看到的應該是乾淨容器——但這個推理在「同 file 內」成立、跨 file 不成立：

• 跨 file 之間 dart test runner 在 file 邊界做的事是不確定的（可能整個 isolate 重啟、也可能只是切換 group）
• 即使前一個 file 的 tearDown 跑完，跨 file 的某個 microtask / timer callback 仍可能在後一個 file 的 setUp 之前 fire
• 用 setUp 開頭的 reset 等於再保險一次、把這個邊界內的不確定性吃掉

除錯思維：flaky test 的固定診斷流程

 11. 看是不是真的 flaky
 2   - 連跑 5~10 次、計算成功率
 3   - 隨機失敗（不是 100% 也不是 0%）→ 進入 flaky 診斷
 4
 52. 找真正的失敗源頭
 6   - 看 progress line `+N -M`、找 -1 第一次出現位置
 7   - 不要直接讀 "did not complete"、那是受牽連訊息
 8
 93. 判斷是 in-file 還是 cross-file 污染
10   - 失敗的 test 單獨跑：
11     - 100% 通過 → cross-file 污染（其他 file 的殘留進來）
12     - 也會隨機 fail → in-file 污染（同 file 的 test 之間互相污染）
13
144. 補對應的隔離
15   - cross-file → setUp 開頭 Get.reset()
16   - in-file → 看是 setUp/tearDown 沒清乾淨還是 test 之間共享 mutable state

教訓

1. did not complete 不是失敗源、是被牽連訊息——往前找 -1 第一次出現的位置才是真正失敗的 test。
2. 單獨跑通過 + 全 suite fail = cross-file pollution——這是 flaky test 最常見的固定模式之一、有專屬的解法（setUp reset）、不要當成「資料時序的隨機性」隨便重跑。
3. tearDown 清不夠、setUp 也要清——任何用 GetX 的 test 應該在 setUp 開頭主動 Get.reset()、不要依賴上一個 file 的 tearDown。
4. 第一次診斷錯誤是常態、要回到證據——順著 fail 訊息修是直覺反應、但訊息可能誤導；停下來看計數欄位、單獨跑驗證、才是穩定的診斷方式。

適用範圍

這個 pattern 不限於 GetX、適用於任何在 process-scoped global state 註冊東西的框架：

• Provider 的 MultiProvider / 全域 instance
• Riverpod 的 ProviderContainer（雖然 Riverpod 設計上更鼓勵 per-test container）
• 自寫的 service locator / singleton
• 任何 static field 累積的狀態

只要框架的 state 跨 test boundary 而 dart test runner 又在同 process 跑多 file，cross-file pollution 都可能發生。setUp 開頭主動 reset 是通用防身術。

參考資料

• Dart package:test runner concurrency docs
• GetX Get.reset() source
• Flutter flutter_test binding lifecycle