概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

概念定位

Flaky test 是非決定性的 gate 訊號。它的危害不只在延遲 merge，而是在心理上訓練團隊忽略紅燈；當真回歸出現時，大家也可能先按 rerun。治理目標是把 flaky 分類、隔離、修復，並保持 required checks 的語意可信。

Detect 階段負責證明 flakiness。單次失敗不應直接貼 flaky 標籤；要看同一 commit、同一測試、相近環境下是否出現 pass / fail 不一致，並保存 log、trace、screenshot 或 seed。

Classify 階段負責找根因方向。常見來源包含時間競態、測試順序依賴、共享狀態、外部服務、隨機資料、資源不足、瀏覽器 layout timing、網路模擬與 CI runner 差異；不同來源需要不同修法。

Contain 階段負責保護主線。高價值但暫時 flaky 的測試可以進 quarantine workflow，但必須有 owner、issue、到期日與 replacement gate；直接從 required checks 移除而不追蹤，等於降低品質基線。

Fix 階段負責消除非決定性。常見修法是移除固定 sleep、改用可觀察條件等待、隔離資料、固定 random seed、避免測試共享全域狀態、mock 不穩定外部依賴或調整資源限制。

Re-admit 階段負責把測試放回 gate。測試修完後應在多次 workflow、不同 runner 或足夠時間窗口中穩定通過，再恢復 required checks；否則 gate 會反覆被污染。

分類矩陣

分類矩陣的責任是讓 flaky issue 有明確修復路由。沒有分類時，團隊容易只留下「偶發失敗」這種不可執行標籤。

這張表的邊界是：flaky 可能來自測試，也可能來自產品 race condition。若測試揭露的是產品 race condition，它應該被當成真 bug 處理。

Quarantine 契約

Quarantine 的責任是暫時隔離污染，並維持 gate 的長期品質基線。隔離測試時，要把責任、期限與替代風險控制寫清楚。

1. 每個 quarantine test 必須有 issue 與 owner。
2. 每個 issue 必須標明分類、失敗證據與修復方向。
3. Required checks 若移除測試，要補 replacement gate 或風險說明。
4. Quarantine workflow 仍需定期跑，並回報趨勢。
5. 到期未修復時要重新評估：修、刪、改寫或降級測試責任。

這個契約讓 quarantine 成為治理工具。沒有期限與 owner 的 quarantine 會變成測試墓地，讓主線 gate 永久失去一部分覆蓋。

Tripwire

Tripwire 的責任是提示 flaky 已經從局部問題變成流程問題。

• 團隊看到紅燈第一反應是 rerun：暫停重跑習慣，要求先分類失敗。
• 同一測試一週內多次 quarantine：提升到測試架構或產品 race 檢討。
• Required checks 常因環境問題失敗：檢查 runner、resource、cache 與外部依賴。
• Flaky issue 沒 owner 或沒期限：把 quarantine 視為未完成修復，不視為已處理。

下一步路由

• Flaky 術語：讀 Flaky Test。
• Failure routing：讀 CI 失敗到修復發布流程。
• Gate 邊界：讀 CI gate 與 workflow 邊界。

核心議題：寫測試時觸及 type system 看不到的 runtime contract — service locator 的注入契約、widget tree 的 framework state、async error 的 try-catch 邊界。三類都要 runtime 才會炸、test 跑到才會曝光。 案例骨幹：Popup.hint 同一條呼叫路徑同時持有 sync 與 async 兩條失敗路徑（缺 service 注入、BotToast 同步 assert、BotToast 從 async gap 後拋 LateInitializationError）。用 runZonedGuarded 把兩條路徑收斂到同一個 fallback handler、用 fallback signature 設計讓訊息不被誤判為 error。

1. Type system 看不到的 runtime contract

flutter analyze（與一般的 type checker）的責任是檢查宣告與名稱層的契約 — 型別一致、import 能解析、識別字能對到符號。它驗證的是「靜態可決定的事」：missing import、undefined method、type mismatch 都會在 compile 前被攔下。

它看不到的是 runtime 才成立的契約，這正是寫測試最容易暴露的盲區：

• Service locator 的注入契約：GetX 的 Get.find<T>()、get_it 的 GetIt.I<T>()、Provider 的 Provider.of<T>() 都是 runtime 查找機制（Map lookup 或 widget tree 上溯，視實作而定）。「呼叫前 T 必須先註冊或在 ancestor 提供」是執行期前置條件，型別系統看不見。
• Framework state 的存在前提：BotToast 需要 widget tree 上有 BotToastInit、Navigator 需要 MaterialApp 包著。這是 framework 的執行期狀態，不是型別。
• late 變數的跨呼叫順序契約：宣告對了不代表用對了。analyzer 對單一檔案內某些 unsafe pattern 能出警告，但「A 函式必須在 B 函式前被呼叫」這類跨呼叫順序契約，型別系統看不見。

這個邊界對「寫測試」的意涵：test setUp 不只是準備資料，更是補上 type system 看不到的 runtime contract — 注入哪些 service、提供哪些 framework state、控制哪些 init 順序。主程式裡那些「靠 widget tree」「靠 service locator」「靠 framework lifecycle」的契約，每一條都對應到 test setUp 的一個責任。

2. 案例：一條呼叫路徑觸及三類邊界

下面以 Popup.hint 對 BotToast.showNotification 的呼叫為例。寫一個跑 AuthService.afterLogin 的 unit test 時，這條呼叫一次觸及 runtime contract 段列的三類邊界：service locator 注入缺失、widget tree 缺 BotToastInit、late 變數在 async 排程後讀取。三組訊號攤開：

第一條的修法是 setUp 補注入。第二條的同步 assert 單獨看，sync try-catch 接得住。但它跟第三條 async error 是同一個 API 的兩種失敗模式 — 包 sync try-catch 只罩到同步那條、async 那條仍漏。

結論：要兩條都接到，需要一個同時 cover sync 與 async 的接管機制。

3. Sync try-catch 與 async error 的邊界

Sync try-catch 的作用範圍是同步調用棧：try block 執行期間棧上拋的錯誤會被接住。一旦執行流程穿越 async 邊界（Future、Timer、microtask 排程），原 try-catch 已經出 scope：

1Popup.hint() {
2  try {
3    BotToast.showNotification(...)   ← 同步返回，立刻離開 try
4      └─ 內部排到下一個 frame 或 microtask {  ← 之後才跑
5           ...拋 LateInitializationError...   ← try-catch 已經出 scope
6         }
7  } catch (e) { ... }
8}

辨識 async unhandled error 的訊號是 stack trace 裡有 ===== asynchronous gap ===== — 它代表錯誤穿越了一個 async 邊界。從 caller frame 來看「沒人在 stack 上」，錯誤會上溯到 zone 的 uncaught error handler；root zone 把它印到 stderr，或讓 flutter_test runner 當作 test failure。

async 函式內的 try-catch 是常見混淆點：寫成 try { await x; } catch (e) 時，try-catch 能接住 await 的 future rejection（await 把 async error rewire 成 sync throw）。但對沒 await 的 fire-and-forget 排程（直接呼叫一個會內部 schedule microtask 的 API），try-catch 的覆蓋範圍止於同步路徑。

風險：fire-and-forget API 的 error 路徑跨 async 邊界

BotToast、analytics、Toast、SnackBar 這類 API 通常同步返回（讓 caller 不必 await），內部排到下一個 frame 或 microtask 做 UI 工作。caller 看到的是同步呼叫，但錯誤可能從 async 邊界後跑出來。caller 端的 sync try-catch 看起來罩住了，實際接不到。

4. 接管機制：runZonedGuarded 同時罩 sync 與 async

接 async unhandled error 要用 zone-aware 機制。runZonedGuarded(body, onError) 建立一個子 zone，任何在這個 zone 內 schedule 的 async work，錯誤都會冒泡到 onError — 不管錯誤穿越幾層 microtask、Timer、Stream。它同時也 cover 同步拋錯，可以取代 try-catch 包住整個 best-effort 邊界：

 1// toast 是 best-effort：BotToast 需要 widget tree (BotToastInit)，
 2// 在非 UI 環境（unit test、isolate）顯示失敗時保留 log、不向 caller 傳遞錯誤。
 3// 用 runZonedGuarded 因為 BotToast 部分錯誤從 async gap 後拋出，sync try-catch 接不到。
 4runZonedGuarded(() {
 5  BotToast.showNotification(
 6    title: (_) => Text(message, style: AppTheme.whiteTextButtonStyle),
 7    backgroundColor: contentColor,
 8    duration: const Duration(seconds: 2),
 9    animationDuration: const Duration(milliseconds: 300),
10    animationReverseDuration: const Duration(milliseconds: 300),
11  );
12}, (error, stack) {
13  if (kDebugMode) {
14    debugPrint('[Popup.hint][fallback] BotToast 不可用，僅記 log：$error');
15  }
16});

機制重點：同一個 onError 同時接住同步的 Failed assertion 與 async 的 LateInitializationError — sync 與 async 兩條失敗路徑收斂到單一 fallback handler，不需要為兩條各寫一套錯誤處理。

5. runZonedGuarded 的責任邊界

runZonedGuarded 把整個邊界的錯誤導向 fallback handler，責任範圍要劃清楚：

zone ≠ thread。Dart 是單線程的，zone 只是邏輯標籤、不涉及並發。它只改變錯誤的去向、不會 cancel 已 schedule 的 work。

注意事項：何時不該用

Zone 歸屬以 schedule 時的 zone 為準、不是執行時 — async 物件「屬於」schedule 它的那個 zone。這個規則讓跨 zone 操作 Timer、Stream 的行為偏離直覺。實務上最常見的觸發場景是 WidgetsFlutterBinding.ensureInitialized() 在 root zone 註冊了 framework binding 後、才用 runZonedGuarded 包 runApp，binding 內部 callback 已綁在 root zone、外層 zone 接不到。Flutter 官方明確建議 ensureInitialized() 跟 runApp() 都在同一個 runZonedGuarded 內。

zone 適合包「整個邊界」：整個 isolate entry、整個 best-effort UI 工作、整個 background task。不適合包關鍵 transaction logic — 那是 try-catch + Future error handling 的責任，zone 是 fallback 收斂層、不是主要錯誤處理。

6. Fallback 訊息設計：可識別的 signature

Fallback path 跑通之後，留在 console 的訊息會被讀到很多次（每次 test 都會跑）。訊息措辭要與設計意圖一致，否則讀者每次都要花心力辨識「這是設計內降級、還是真的 bug」。

風險：fallback 長得像 error

直覺寫法 debugPrint('toast 顯示失敗：$error') 加上 framework 的 assert stack，字面看起來就是個 error。讀者第一眼會緊張、要花心力比對程式才能確認「這是設計內路徑」。test 跑很多次、每次都付一次辨識成本。

三條設計原則

Fallback path 要有可識別的 signature（標籤、prefix、特定字眼）、長得不像 error。對人類讀者，prefix 是視覺上一眼識別「設計內路徑」；對工具，grep -v "\[fallback\]" 可快速剔除 test 輸出裡的預期降級訊息。

字眼要表達因果與處置：「BotToast 不可用，僅記 log」比「顯示失敗」更完整 — 前者說了為什麼降級、後者只描述現象。寫 fallback 訊息要回答兩個問題：為什麼進這條路徑、降級到哪。

主程式不該感知測試框架：主程式 import dart:io、查 Platform.environment['FLUTTER_TEST'] 等於「主程式對自己被 test 跑」有意識 — 這違反「主程式不該知道 test 存在」的原則，test 框架是 caller 的事、不是 callee 的事。違反後續成本：app 行為依賴環境變數時，QA / staging / production 的環境一致性會多一條檢查線。

三個候選方案在原則上的取捨

下列三個方案分別在「signature 識別度」「主程式對 test 框架感知」「dev 可見性」三條原則上做不同取捨：

為什麼選 A

保留 dev 訊號（BotToast 在 dev app 真的壞時 console 仍會印） + 主程式對 test 框架無感知 + prefix 雙贏（人類視覺辨識 + grep 過濾）。方案 C 完全靜默會失去保險、dev 環境真壞時看不見；方案 B 雖然 test 輸出乾淨，代價是違反設計原則。

7. 設計副產物：修主程式對缺依賴的容錯

Popup.hint 對「沒有 widget tree」連環倒，這個失敗不只 unit test 會遇到 — isolate 內、background task 內、任何非 UI 環境都會炸。修 test 順手把主程式對缺依賴的容錯加上，是合理副產物：unit test 是觸發訊號、主程式被觸發後變得更能適應多元 caller 環境，這個改動的受益面大於原本 test 暴露的那個情境。

主程式變 robust 的價值大於「讓 test 過」。修主程式對 caller 環境的容錯時要分辨「容錯」與「掩蓋」的界線：log 仍要留、fallback signature 仍要可識別（Fallback 訊息設計段），錯誤完全靜默會讓 dev app 真壞掉時也看不見。

適用範圍

runZonedGuarded 適用情境：

• Fire-and-forget 的 UI 通知：Toast、SnackBar、analytics 上報；這些是 best-effort，caller 連環倒不合理。
• Isolate entry point：spawn 出來的 isolate 沒有預設 error handler，包一層 zone 才不會靜默掛掉。
• Background task / Timer 包裝：long-running periodic job 內部錯誤不該炸掉整個 process。
• flutter_test 內掛 Stream / Future 驗證：把測試體包進 zone 才能完整接 async 拋出的東西。

「Type system 看不到的 runtime contract」適用任何用 service locator / DI 容器、framework state、late init 的 Flutter 專案。Test 是這些 runtime contract 的事實驗證者 — analyze 過了不代表這些契約沒破，test 跑到才會炸。

參考資料

• Dart runZonedGuarded API
• Dart Zone 概念與 zone-local variables
• Flutter Zone mismatch breaking change — ensureInitialized() 與 runApp() 必須同 zone
• flutter_test async error 處理機制
• 同主題本站文章：Dart test 的跨檔案 GetX 狀態污染 — 另一種「test 環境組裝不完整」的 case

事故類型：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