辨識特徵

app_tunnel 的 connection_flow_test.dart 是具體案例。檔名標題是端對端整合測試，但內部使用了三個核心替身：FakeWebSocketChannel、FakeBiometricService、InMemoryCredentialRepository（T.C2）。

名義 integration test 有三個共同特徵可用來辨識。

特徵一：核心外部依賴全替換

Integration test 的價值在於驗證程式碼與外部系統的互動邊界。如果所有外部依賴都被 fake 取代，test 驗證的實際上是「假設外部系統行為符合開發者預期，內部邏輯是否正確」。這和 unit test 的差別只在 scope 大小 — 多個內部元件一起測 — 不在驗證對象的本質。

判斷方式：列出 test 的所有依賴注入點，計算有多少外部服務被替換成 fake。如果 100% 的外部依賴都是 fake，這個 test 不驗證任何真實互動。

特徵二：沒有真實的 I/O 操作

真正的 integration test 會產生真實的網路連線、讀寫真實的檔案、或呼叫真實的 API endpoint。名義 integration test 的所有 I/O 都在 process 內部完成 — StreamController 替代網路 stream，Map<String, String> 替代資料庫，Future.value() 替代非同步 I/O。

這些替身讓 test 執行速度快、結果穩定，但代價是完全跳過了 I/O 邊界上的所有行為差異。

特徵三：沒有環境前置條件

真正的 integration test 需要外部環境準備：啟動服務、建立連線、準備測試資料。名義 integration test 的 setUp() 只建立 fake 物件，不啟動任何外部程序，不需要網路，可以在任何環境下執行。

環境前置條件的缺席是一個實用的快速判斷訊號。如果 setUp() 裡沒有 docker compose up、Process.start、HttpClient.connect 之類的操作，這個 test 很可能不接觸真實外部服務。

名義 integration test 造成的認知偏差

名義 integration test 的技術問題可以修正（改名或補寫真實 integration test），但它造成的認知偏差更難修正。

當團隊看到 test suite 包含「integration test」資料夾且全部通過，決策者的推論是「integration 已經驗證過了」。這個推論在名義 integration test 下是錯的 — 協議層和環境層完全沒被驗證 — 但決策者沒有動機去檢查 test 的內部實作。

app_tunnel 的 11 個 connection_flow_test 全過，開發者合理認為「連線流程的整合測試已通過」。實際上這 11 個 test 驗證的是 ConnectionManager 的內部狀態機在各種情境下的轉換正確性（斷線重連、錯誤處理、狀態回報），不是「和 ttyd 的連線流程是否正確」。Auth handshake 缺失直到實機測試才被發現。

修正策略

修正命名

最低成本的修正是讓 test 名稱反映真實驗證對象。命名改動不影響 test 本身的價值 — 這些 test 驗證內部狀態機的邏輯仍然有用 — 只是消除命名造成的認知偏差。

補寫真實 integration test

命名修正只消除誤解，不補上缺失的驗證層。如果服務的協議互動是關鍵路徑（連線、認證、資料交換），需要補寫對真實服務的 protocol integration test。

補寫的判斷原則不在本章展開 — 見 判斷原則：什麼時候需要 protocol integration test。

在 test 檔案內標明依賴替換清單

在 test 檔案的頂部註釋中列出所有被 fake 取代的依賴，讓後續讀者不需要逐行追蹤就能判斷這個 test 的驗證邊界。

1// Faked dependencies: WebSocketChannel, BiometricService, CredentialRepository
2// Verifies: ConnectionManager state machine transitions
3// Does NOT verify: real WS protocol, auth handshake, biometric hardware

下一步路由

• 判斷是否需要補寫真實 integration test → 判斷原則：什麼時候需要 protocol integration test
• Mock 遮蔽機制的完整分析 → Mock 遮蔽機制分析
• 想建 protocol integration test → 模組三：協議整合測試

三個判斷問題

斷言的是行為嗎

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 邊界判斷決策表