閘門 spike：編排的宿主能不能在 headless 環境立起來

流程測試要驅動的是控制器裡的真實編排——順序約束、防護動作、收尾同步——而 Flutter 的控制器在 onInit 常帶平台耦合（platform channel 訂閱、相機偵測、外接裝置 plugin）。這些耦合在 headless 測試環境全部失效。

開工前先做一條最小測試 spike：能否建構控制器並呼叫編排入口。spike 的答案決定整個套件形態——立得起來就直接驅動真實編排（零漂移），立不起來要先評估重構接縫的成本。

平台耦合的中和工具在 Dart 生態有固定的對應：

時序欄位承載的是這張表最容易踩的陷阱：EventChannel 的訂閱發生在 plugin 建構子裡，晚一步掛 mock，訂閱已經對著真實 channel 成立、之後補掛不會回溯生效——症狀是測試偶發卡在等事件。MethodChannel 的容錯高一些（呼叫當下才查 handler），但同樣要在第一次呼叫前就位。no-op 子類優於 mock 框架的場景：要中和的成員少（覆寫列表一目瞭然）、其餘行為要保留真實。流程測試的精神是假件越少，測試的證言越可信——這裡指的是平台耦合層的假件（與被驗編排無關的雜訊），被測邊界本身的假後端是另一回事，它的設計判準與忠實性把關見語意級假後端。

這套 channel mock 加 no-op 子類的組合（後文稱 harness）一旦成立就收斂為共用 bootstrap 方法——之後每條流程測試的邊際成本只剩劇本本身。完整 case 與程式碼範例：讓 UI 控制器在 headless 測試立起來。

兩種測試的共存：binding 的檔案級 isolate 隔離

流程測試需要 TestWidgetsFlutterBinding（mock channel、立控制器），真實後端驗證測試需要真實網路——兩者互斥。TestWidgetsFlutterBinding.ensureInitialized() 的副作用之一是把 dart:io 的 HttpClient 換成一律回 400 的假件，且這個副作用是程序級全域、沒有乾淨的關閉開關。

共存機制不需要額外設計：flutter test 讓每個測試檔案跑在獨立 isolate，而 isolate 之間記憶體不共享——binding 換掉的全域物件只在自己的 isolate 內生效，副作用因此以檔案為邊界。

硬約束：真實後端驗證測試的檔案不可 import 流程測試的 harness——harness 為了 mock channel 第一步就是 ensureInitialized，import 進來即使不直接呼叫，任何共用 helper 順手初始化都會中招。違反這條約束的症狀是「穩定 400、無網路痕跡」——症狀與原因之間距離太遠，值得寫進檔頭。

真實後端驗證檔裡繞開產品 DI 的做法：手組最小可用的 Dio，請求與解析仍走產品的 API client 與模型（型別化解析層共用、不手寫 JSON）。完整機制與程式碼：TestWidgetsFlutterBinding 會擋掉真實網路。

輸出雜訊治理：預期環境狀態的正確處理路徑

harness 立起後，測試輸出可能固定印出幾行「錯誤長相」的文字——相機偵測的 MissingPluginException、toast 套件的 assert fallback。這些在生產環境是正確的防護路徑，在測試環境是必然觸發的假警報。假警報訓練人忽略輸出，新的真警報混在裡面就被同一個心理過濾器吃掉。

治理原則：測試環境 100% 必然成立的觸發條件，用前置判斷或 harness mock 讓它走正常路徑，讓例外接管只剩真正的例外。

前置判斷放在 runZonedGuarded 的 zone 內而非外——極端環境（binding 未初始化）連 WidgetsBinding.instance 都會拋，放 zone 內讓它落入兜底。分工因此變乾淨：前置判斷處理已知的環境狀態，zone 兜底處理未知的失敗。完整案例與判準：測試輸出的雜訊治理。

假後端的回應序列化：物件 → toJson，不是手寫 JSON

有狀態假後端的回應資料從哪裡來，是 Dart 生態特有的選型：freezed 模型天生雙向（fromJson/toJson），假後端持有模型物件、出口一律 toJson()，服務層走的反序列化路徑與生產環境完全相同。

手寫 JSON 樣板跳過這個閉環的前半段——樣板對不對靠人眼比對 API 文件。實際案例：同一批測試裡的 raw 寫法重踩了產品早已內建處理的分頁包裝（信封解析層的知識被重複實作在測試 helper 裡），改走產品的 API client 與模型後，helper 連同它代表的重複知識一起刪除。

判準一句話：回應形狀的知識只該存在一份。測試裡出現 data['data'] 之類手挖回應欄位的 helper，就是重複知識的訊號。

假後端的狀態演變用 copyWith 在 handler 裡宣告式完成，一個 handler 對應一條已證實的後端行為。toJson 閉環的忠實性由配對的真實後端驗證測試把關——模型的 fromJson/toJson 若與真實後端不對稱，會在那裡先於產品爆出來。完整做法與對照組事故：有狀態假後端用真實模型序列化回應。

建置順序

四個限制的處理有先後依賴：

1. spike：一條最小測試驗證控制器能否在 headless 環境建構並呼叫編排入口
2. harness 收斂：spike 過了之後，把 channel mock + no-op 子類 + postFrameCallback 補位收進共用 bootstrap
3. 檔案隔離規劃：真實後端驗證測試另開檔案、不 import harness、不初始化 binding
4. 雜訊治理：harness 的 channel mock 順便解決大部分雜訊；剩餘的 headless 環境假警報加前置判斷
5. 假後端序列化：以 freezed 模型持有狀態、toJson 出口，seed builder 集中維護初始狀態
6. 第一條劇本：走完一段跨服務業務旅程，斷言散佈在各階段的可觀察結果上

步驟 1 決定後續全部形態——立不起來就回到策略層重新評估（語意級假後端與流程測試的「可測性閘門」段）。

下一步路由

• 策略層的完整判準（什麼時候值得建假後端）→ 語意級假後端與流程測試
• 配對的真實後端驗證（假後端行為漂移的防線）→ 真實後端驗證測試
• 憑證的存放與 CI 注入 → 測試憑證管理
• 各限制的完整 case：headless 控制器、binding 互斥、雜訊治理、假後端序列化

核心議題：測試環境沒有相機、沒有 widget tree——這些是必然且預期的狀態，但程式用「拋例外→catch→印 log」的路徑處理它們，於是每次跑測試都固定印出兩行看起來像壞掉的輸出。人對重複出現的警報會建立心理過濾，等真的有新問題印出相似訊息時，一起被過濾掉。 案例骨幹：POS App 的流程測試輸出固定出現「偵測相機失敗（MissingPluginException）」與「toast 套件不可用（assert 失敗）」。使用者的裁定是：無法使用的就該移除、可疑的要查清是什麼——結果一個在 harness 補 channel mock 讓偵測走正常路徑，一個查證為環境必然後改成前置判斷，例外接管降級為真正非預期的兜底。

1. 兩行雜訊的解剖

兩者共同點：觸發條件在測試環境是 100% 必然。每一次執行、每一條會經過這些路徑的測試，都固定貢獻幾行「錯誤長相」的輸出。

2. 為什麼要治理：已知雜訊遮蔽新警報

單看無害——catch 有接、fallback 有兜、測試全綠。傷害在人這一側：讀輸出的人很快學會「那兩行不用看」，心理過濾建立後，過濾的是模式不是內容——某天一行真正的新錯誤以相似的形狀出現（另一個 MissingPluginException、另一個 assert fallback），會被同一個過濾器吃掉。

治理原則一句話：測試輸出裡的每一行錯誤長相的文字，都應該值得停下來看。做不到就治理到做得到。

3. 修法一：讓偵測走正常路徑（harness 補 channel mock）

相機那行的問題不是 catch 寫錯——生產環境「枚舉失敗保守視為無相機」是正確防護。問題是測試環境讓它天天走例外路徑。修在 harness：

1// 測試環境沒有相機 plugin，回空清單讓啟動期的相機偵測
2// 得到「無相機」的乾淨結果，不走例外路徑留下雜訊 log。
3TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
4    .setMockMethodCallHandler(const MethodChannel('plugins.flutter.io/camera'),
5        (call) async => call.method == 'availableCameras' ? <dynamic>[] : null);

偵測照常執行、得到空清單、安靜地判定無相機。產品碼一行不動。

4. 修法二：預期狀態前置判斷，例外接管留給非預期

toast 那行先查證：正式 App 在根 widget 正確掛了套件的初始化 builder——不是產品 bug，assert 純粹是 headless 環境沒有畫面。既然「無畫面」是可以直接判斷的狀態，就不該用「撞 assert → zone 接住」的方式發現它：

1runZonedGuarded(() {
2  // 無畫面（headless 測試等）時 toast 沒有掛載點；
3  // 訊息已先記進 log 服務，略過顯示即可
4  if (WidgetsBinding.instance.rootElement == null) return;
5  showToast(...);
6}, (error, stack) {
7  // 這裡從此只會接到真正非預期的失敗——留著的 log 才是警訊
8});

分工因此變乾淨：前置判斷處理已知的環境狀態，runZonedGuarded 兜底處理未知的失敗。兜底的 log 從「每次測試都響的假警報」變成「響了就該查」的真警報——這才是兜底該有的信噪比。（zone 接管機制本身的分析見 sync try-catch 接不到 async 錯誤。）

前置判斷放在 zone 內而非 zone 外有一個小理由：極端環境（binding 未初始化）連 WidgetsBinding.instance 都會拋，放 zone 內讓這種罕見情況也落入兜底而不是炸到 caller。

5. 可複用的判準

1. 測試輸出固定出現的錯誤長相文字 = 治理對象，不因「無害」豁免——它的成本收在未來某次被過濾掉的真警報上。
2. 分類處理：觸發條件在測試環境必然成立 → 前置判斷或 harness mock 讓它走正常路徑；觸發條件不確定 → 保留例外接管，且它的 log 要因稀有而醒目。
3. 動手前先查證「這是誰的問題」——toast 那行若不查，可能誤修產品的初始化；查證後才知道是環境必然，修法完全不同。
4. fallback 的價值與它的觸發頻率成反比：天天觸發的 fallback 是常態路徑的錯位，不是防護。

下一步

• zone 與 async 錯誤接管的機制層 → sync try-catch 接不到 async 錯誤
• harness 的完整組裝 → 讓 UI 控制器在 headless 測試立起來

核心議題：跨服務的流程測試若只在 service 層打轉，控制器裡的編排（順序、防護動作、收尾同步）就是測不到的盲區——而實戰裡的 bug 恰好密集出現在編排層。能否直接 Get.put(控制器) 立起真實控制器，是套件形態的閘門問題，值得用一條最小測試先做 spike。 案例骨幹：POS App 的主控制器在 onInit 做四件與平台耦合的事（掃碼廣播、相機偵測、外接顯示器、frame callback）。逐一拆解後發現全部可以在 headless 環境用低成本手段中和——spike 首跑即過，此後所有流程測試都能驅動真實編排、零複製漂移。

1. 為什麼非立起控制器不可

替代方案是「測試裡複製編排步驟」：service 層一步步照著控制器的順序呼叫。它能跑，但有結構性缺陷——控制器改了順序、測試不會知道，兩邊靠註解互指維持同步。這個漂移風險不是理論：同一個專案裡，一個「刷新要在列表同步之後」的順序約束，正是靠流程測試驅動真實編排才抓到的（複製版測試當時是綠的）。

所以開工前先回答閘門問題：控制器立不立得起來？ 答案決定套件形態，用一條最小測試 spike，不要寫到一半才發現。

2. 四個啟動期障礙與各自的中和手段

控制器 onInit 的每一項平台耦合，對應一個測試側的責任：

channel mock 的兩個 API 各對一種 channel：

1// EventChannel：plugin 建構子就會 listen，必須在建立前掛好
2TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
3    .setMockStreamHandler(const EventChannel('channel-name'),
4        MockStreamHandler.inline(onListen: (args, events) {}));
5
6// MethodChannel：讓查詢類呼叫得到正常的空結果，而非例外
7TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
8    .setMockMethodCallHandler(const MethodChannel('channel-name'),
9        (call) async => call.method == 'query' ? <dynamic>[] : null);

「建構子就訂閱 EventChannel」是其中最陰的一個——mock 掛晚了炸在 new 的當下，錯誤點在別人的 package 深處。判準：引入外接硬體類 plugin 時，先看它的建構子做了什麼。

3. no-op 子類 vs mock 框架

掃碼廣播服務的替換用的是手寫子類而不是 mock 框架：

1class SilentBroadcastService extends BroadcastService {
2  @override Stream<Message> get messages => const Stream.empty();
3  @override Future<void> start() async {}
4  @override Future<void> stop() async {}
5}

理由：要中和的只有「碰平台」的三個成員，其餘行為保留真實；子類的差異一目瞭然，mock 框架在這裡只會增加閱讀成本。這與「服務鏈盡量走真實實作」的流程測試精神一致——假的東西越少，測試的證言越可信。

4. 立起來之後：非同步收尾的等待紀律

控制器編排常見 fire-and-forget（收尾動作不 await 就返回）。測試斷言若緊跟在呼叫後面，就是在跟背景收尾賽跑——單獨跑碰巧贏、整批跑排程不同就輸。等待紀律：

1await controller.checkout();
2for (var i = 0; i < 100; i++) {
3  if (終態條件到達) break;      // 狀態已清除、計數已到位
4  await pumpEventQueue();      // 沖刷 microtask 與已到期 timer
5}

輪詢「可觀察的終態」而非固定 sleep——固定延遲只是把起跑線挪後，在更慢的環境照樣輸。通用層的分析見 T.C8 fire-and-forget 編排的測試競態。

5. 可複用的判準

1. 流程測試開工前，先 spike「編排的宿主立不立得起來」——答案改變整個套件的寫法。
2. 控制器啟動期的每一項平台耦合 = 測試 harness 的一項責任；逐項列表處理，不要碰到一個修一個。
3. EventChannel 的 mock 要在「任何會建構該 plugin 物件的程式」之前掛好。
4. postFrameCallback 承載的初始化，在純 test 環境要手動補跑，並在兩處註明對應。
5. harness 一旦成立就收斂為共用 bootstrap——之後每條流程測試的成本只剩劇本本身。

下一步

• harness 與真實網路測試的互斥約束 → TestWidgetsFlutterBinding 會擋掉真實網路
• 這個形態的完整方法論 → 語意級假後端與流程測試