決策依據

Mock 夠用的場景

Test 驗證的行為完全在程式碼內部 — 函式邏輯、狀態機轉換、資料轉換、錯誤處理分支。這些行為不依賴外部服務的協議細節，mock 提供的 API 層模擬已經足夠。

判斷問題：如果把 mock 替換成真實服務，test 的斷言結果會不會改變？ 如果不會改變，mock 夠用。

例：ConnectionManager 收到 error 後是否正確切換到 error 狀態 — 不管 error 來自 mock 還是真實 WebSocket，狀態機邏輯相同。Mock 夠用。

Mock 不夠的場景

Test 要驗證的行為涉及外部服務的協議行為 — frame type 差異、認證流程、編碼格式、逾時行為。Mock 的 API 層模擬跳過了這些行為，test 通過不代表真實互動也通過。

判斷問題：Mock 跳過了外部服務的哪些步驟？這些步驟的行為是否影響 test 要驗證的結果？ 如果是，需要 protocol integration test（testing 模組三）。

例：sendData() 發送鍵盤輸入 — mock 的 sink.add(dynamic) 接受任何型別，但真實 IOWebSocketChannel 對 String 和 Uint8List 產生不同 frame type。Mock 不夠。

決策表

灰色地帶的判斷

有些 test 介於「mock 夠用」和「mock 不夠」之間。例如驗證「連線失敗時顯示 error 訊息」— 觸發失敗的方式可以是 mock 回傳 error（驗證顯示邏輯），也可以是真實服務拒絕連線（驗證真實失敗場景的處理）。

灰色地帶的判斷策略是：用 mock test 驗證「收到 error 後的處理邏輯」，用 protocol integration test 驗證「真實服務在什麼情況下回傳 error」。兩層 test 各自回答不同問題，不互相替代（testing 模組一 三層定義）。

Mock 邊界確定後，另一個影響 test 有效性的因素是測試資料的代表性 — 測試輸入能否反映真實環境。Mock 遮蔽的結構性原因在 testing 模組一 Mock 遮蔽機制分析中完整展開，判定需要真實服務後的成本評估見 testing 模組三 成本判斷表。

代表性問題的案例

app_tunnel 的 ANSI parser 有 18 個 test，全部通過。測試資料是手寫的 SGR 色彩碼（\x1B[31mhello\x1B[0m），parser 正確解析這類序列。

真實 zsh 啟動後送出的控制序列包含 OSC 標題設定、CSI private mode、字元集指定等至少 5 種類型。Parser 只認識 SGR，其他全部透傳為亂碼（T.C3）。

18 個 test 覆蓋了 1 種序列類型。測試資料的代表性假設（「SGR 就是主要的序列類型」）和真實環境不符。

三種測試資料來源

手寫

開發者根據對輸入格式的理解手動建構測試字串。

優點：精確控制、容易理解、可以針對特定邊界條件設計。

缺點：受限於開發者對輸入分佈的認知。如果開發者不知道真實環境有哪些輸入類型，手寫的測試資料就是開發者認知的子集 — T.C3 就是這個模式。

適合場景：格式規格明確且有限（JSON schema、固定格式的設定檔）、邊界條件測試（空值、最大長度、特殊字元）。

錄製

從真實環境擷取實際的輸入資料，作為 test 的輸入。

優點：直接反映真實環境的輸入分佈，包含開發者不知道的輸入類型。

缺點：錄製的資料可能包含敏感資訊（需要脫敏）、資料量可能大（需要挑選代表性樣本）、真實環境的輸入可能隨時間改變（錄製的資料可能過時）。

適合場景：輸入格式複雜且規格不完整（終端機 escape 序列、網路封包、使用者產生的內容）、parser 類的功能（需要知道「真實輸入長什麼樣」）。

T.C3 如果用錄製的真實 zsh 啟動輸出作為測試資料，OSC 和 CSI private mode 會自然出現在輸入中。即使 parser 仍然不處理這些序列，test 至少能讓開發者看到「有 5 種序列類型，我只處理了 1 種」。

生成（Property-based testing）

用 generator 自動產生大量隨機或半隨機的輸入，驗證 parser 的行為是否符合通用性質（不崩潰、輸出長度 <= 輸入長度、冪等性）。

優點：覆蓋人類想不到的 edge case、發現意外的崩潰或無限迴圈。

缺點：不針對特定功能驗證（驗證的是通用性質，不是「OSC 序列是否被正確處理」）、generator 本身需要維護。

適合場景：parser、serializer、codec 等輸入格式複雜的功能。和手寫 test 互補 — 手寫驗證特定行為正確性，生成驗證通用穩定性。

兩類 test 的分工

T.C3 的策略建議是把 test 分成兩類：

功能正確性 test：用手寫乾淨字串驗證 parser 對已知序列的處理正確性。\x1B[31mhello\x1B[0m 應該產生紅色 token — 這是功能規格的驗證。

環境相容性 test：用錄製的真實輸出驗證 parser 在真實環境中的表現。不斷言「每個序列都被正確處理」，而是斷言「沒有崩潰」「沒有未處理序列殘留在可見輸出中」。

兩類 test 回答不同問題。功能正確性回答「parser 的邏輯對不對」，環境相容性回答「parser 在真實環境中夠不夠用」。

下一步路由

• Assertion 的品質判斷 → Assertion 品質三問
• Mock 邊界的判斷 → Mock 邊界判斷決策表
• Protocol integration test 用真實服務輸出 → testing 模組三 WebSocket 協議測試

三個判斷問題

斷言的是行為嗎

Assertion 應該斷言程式碼的外部可觀察行為（回傳值、狀態變化、副作用），而非內部實作細節（私有變數的值、呼叫次數、執行順序）。

斷言行為的 test 在重構時不需要改 — 只要行為不變，test 就通過。斷言實作的 test 在任何內部調整時都會壞掉，即使行為完全正確。

例：驗證「parser 正確解析紅色文字」時，斷言 token 的顏色屬性（行為）比斷言 parser 內部的 state machine 走了哪些步驟（實作）更穩定。

能區分正確和錯誤嗎

Assertion 應該在程式碼正確時通過、錯誤時失敗。如果 assertion 無論程式碼正確或錯誤都通過，這個 assertion 沒有提供保護。

常見的無效 assertion：

斷言不為 null：expect(result, isNotNull) 只驗證「有回傳值」，不驗證「回傳值正確」。回傳錯誤的值也會通過。

斷言型別：expect(result, isA<List>()) 只驗證「回傳 List」，不驗證 List 的內容。空 List 和錯誤內容的 List 都會通過。

斷言包含：expect(result, contains('error')) 驗證字串包含 ’error’，但如果回傳 ’no error occurred’（正確情境）也包含 ’error’ — assertion 無法區分正確和錯誤。

T.C3 的 parser test 斷言 expect(tokens.first, isA<TextToken>()) — 驗證 token 型別是 TextToken。但正確解析和透傳亂碼都可能產生 TextToken，assertion 無法區分（本章合成，TF-5 Derive — 透傳的靜默副作用和 assertion 的區分力有 tension）。

會 flaky 嗎

Assertion 是否依賴非確定性因素 — 時間、隨機數、外部服務狀態、執行順序。如果是，test 可能在程式碼正確時失敗（false negative），降低團隊對 test 的信任。

常見的 flaky assertion 來源：

• 依賴 DateTime.now() 或 stopwatch.elapsed — 時間精度和系統負載影響結果
• 依賴特定的執行順序 — Set 或 Map 的迭代順序不保證
• 依賴外部服務的回應時間 — 網路延遲導致 timeout

Assertion 改善的操作步驟

對既有的 test assertion 逐一問三個問題，標記需要改善的：

1. 行為 check：assertion 斷言的是 public API 的回傳值或狀態嗎？如果斷言私有變數或呼叫次數，考慮改成行為斷言。
2. 區分 check：把 assertion 改成反向（expect(result, 'wrong_value')），test 會失敗嗎？如果 assertion 太寬鬆（isNotNull、isA），test 可能在錯誤的情況下也通過。
3. 穩定 check：連續跑 10 次，每次都通過嗎？如果有 flaky，找到依賴的非確定性因素。

下一步路由

• Flaky test 的系統性根因分類 → Flaky test 根因分類
• 測試資料的代表性 → Test data 代表性
• Mock 邊界判斷 → Mock 邊界判斷決策表

四類根因

計時依賴

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。