閘門 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 互斥、雜訊治理、假後端序列化

核心議題：TestWidgetsFlutterBinding.ensureInitialized() 的副作用之一是把 HttpClient 換成一律回 400 的假件（防止 widget test 意外打真實網路）。POS App 要在測試套件裡加一層「對真實後端驗證行為」的測試時，這個副作用成為硬約束。 案例骨幹：真實後端驗證測試與流程測試住在同一個 test/integration/ 目錄；前者不可初始化 binding、不可 import 流程測試的 harness（harness 第一行就 ensureInitialized）。兩者能共存的原因是 flutter test 讓每個測試檔案跑在獨立 isolate——binding 的全域副作用以檔案為邊界。

1. 症狀：測試裡所有真實 HTTP 請求回 400

對真實後端（QA 環境）發請求的測試，若與一般測試共用同一個 setup，會得到一個誤導性極強的症狀：請求沒有網路錯誤、沒有逾時，而是穩定回 400。看起來像後端拒絕，實際上請求根本沒離開測試程序。

機制：TestWidgetsFlutterBinding 初始化時安裝 HttpOverrides，把 dart:io 的 HttpClient 換成假實作——這是 flutter_test 的刻意設計，避免 widget test 因為 Image.network 之類的呼叫打到真實網路造成不穩定。它保護了大多數測試，也無差別地擋掉了「就是要打真實網路」的那一種。

2. 約束的傳染性：不可 import 會初始化 binding 的東西

這個副作用是程序級全域的，且沒有乾淨的關閉開關（HttpOverrides.global = null 可以事後拆除，但依賴「記得拆」的紀律，且 binding 的其他副作用仍在）。更穩的做法是把它當成檔案級的硬約束：

• 真實後端驗證測試的檔案從頭到尾不初始化 binding
• 因此也不可 import 流程測試的 harness——harness 為了 mock platform channel、立起 UI 控制器，第一步就是 ensureInitialized；import 進來即使不呼叫，任何一個共用 helper 順手初始化都會中招

這條約束值得寫在檔案頭部的註解裡，因為違反它的症狀（400）與原因（binding）之間的距離太遠，下一個維護者幾乎不可能自己連起來。

3. 共存機制：檔案級 isolate 隔離

看似矛盾的需求——同一個目錄裡，流程測試需要 binding（mock channel、UI 控制器）、真實後端測試不能有 binding——不需要任何額外設計就能共存，因為 flutter test 的執行模型是每個測試檔案一個獨立 isolate：

推論：binding 相關的全域副作用，思考單位是「檔案」而不是「目錄」或「套件」。同目錄混放兩種測試完全安全；同檔案混放必炸。

4. 真實後端測試的請求層組裝

不初始化 binding 之後，還要繞開產品 HTTP 層的執行環境依賴。產品的 Dio 由 DI 容器組裝，攔截器依賴登入服務（token）與翻譯資源（語系前綴）——在無 binding、無 DI 的測試檔裡拉不起來。做法是手組最小可用的傳輸層、但請求與解析仍走產品的 API client 與模型：

1final dio = Dio(BaseOptions(
2  baseUrl: '$baseUrl/$languagePrefix',   // 語系前綴改由 baseUrl 提供
3  connectTimeout: const Duration(seconds: 5),
4));
5final api = ApiClient(dio);              // retrofit client 只需要一個 Dio
6// 登入後手動掛 token，取代攔截器
7dio.options.headers['Authorization'] = 'Bearer $token';

「走產品的 client 與模型」是刻意選擇：手刻 raw JSON 曾在同一批測試裡重踩產品早已解決的問題（列表回應的分頁包裝），而型別化解析讓後端回應形狀的變化在這層先於產品爆出來。

5. 可複用的判準

1. 測試出現「穩定 400、無網路痕跡」→ 先查是不是 binding 的 HttpClient 假件，再查後端。
2. 需要真實網路的測試檔：不初始化 binding、不 import 任何會初始化的模組，約束寫進檔頭。
3. 兩種測試同目錄共存靠檔案級 isolate——組織測試時以檔案為 binding 副作用的邊界單位。
4. 繞開 DI 不等於繞開產品程式碼：傳輸層手組、解析層共用。

下一步

• 這層測試的完整設計（預設可執行、離線降級、憑證失效紅燈）→ 真實後端驗證測試
• harness 那一側的組裝 → 讓 UI 控制器在 headless 測試立起來