三層的職責邊界

Unit Test：驗證程式碼邏輯

Unit test 驗證的對象是「開發者寫的程式碼是否按預期運作」。它的輸入和輸出都在程式碼控制範圍內 — 函式的參數、回傳值、狀態變化、例外拋出。

Unit test 的盲區是所有程式碼以外的東西。外部服務的協議行為、網路傳輸的編碼方式、作業系統的檔案鎖定機制 — 這些不在 unit test 的驗證範圍內，因為 unit test 用 mock 取代了這些外部依賴。Mock 忠實模擬的是程式語言層面的 API 契約（方法簽名、參數型別、回傳值），不是外部服務的協議行為。

app_tunnel 的 192 個 unit test 全部通過，但實機連線後鍵盤輸入無回應。原因是 WebSocket 的 text frame 與 binary frame 差異屬於協議層語意 — FakeWebSocketChannel 的 sink.add(dynamic) 接受任何型別，不區分 frame type（T.C1）。192 個 test 驗證的是「Dart 程式碼邏輯正確」，沒有任何一個 test 的職責是驗證「ttyd 收到的 frame type 是否正確」。

Protocol Integration Test：驗證真實協議互動

Protocol integration test 驗證的對象是「程式碼和真實外部服務之間的協議互動是否正確」。它不用 mock，而是對真實的服務實例發送請求，觀察真實的回應。

這一層的驗證目標包括：連線握手是否完成、認證流程是否正確、資料編碼是否符合對方期望、逾時行為是否合理。這些問題的答案不在程式碼裡，而是在程式碼與外部服務的互動過程中。

app_tunnel 的 auth handshake 缺失就是典型案例。ttyd 要求連線後發送 auth token JSON frame，但 ConnectionManager 沒有實作這個步驟 — FakeWebSocketChannel.ready 立即完成不需認證，所有 test 看到的都是連線成功（T.C2）。對真實 ttyd 執行一個「連線後不發 auth token，斷言 timeout」的 test，就能暴露這個缺失。

Screen State Test：驗證畫面狀態完整性

Screen state test 驗證的對象是「使用者可見的畫面狀態是否覆蓋所有情境」。它的關注點是畫面層級的狀態機 — loading、connected、error、reconnecting 等狀態之間的轉換是否完整，每個狀態下使用者看到什麼、能操作什麼。

Screen state test 和 unit test 的區別在於斷言對象：unit test 斷言「函式回傳值是否正確」，screen state test 斷言「使用者看到的畫面是否正確」。同一段程式碼邏輯可能 unit test 通過（回傳值正確）但 screen state test 失敗（畫面沒顯示對應狀態），因為 UI 層的 binding 有問題。

三層對照

數量與覆蓋率的關係

測試數量和測試覆蓋率是兩個獨立的維度。192 個 unit test 提供的是 unit test 層的覆蓋率 — 程式碼邏輯的分支覆蓋。把 unit test 從 192 個加到 500 個，增加的仍然是同一層的覆蓋率，不會跨越到協議層或畫面層。

層級缺失的問題無法用數量解決。如果整個 test suite 只有 unit test，即使覆蓋率 100%，protocol integration test 層和 screen state test 層的覆蓋率仍然是 0%。app_tunnel 的經驗是：在 unit test 層加更多 test 不會讓 frame type 問題浮現，因為 FakeWebSocketChannel 的行為在每一個 test 中都是一致的 — 一致地遮蔽了協議層差異。

下一步路由

• Mock 如何在 API 層和協議層之間製造盲區 → Mock 遮蔽機制分析
• 如何辨認「名義 integration test」 → 名義 integration test 的識別與修正
• 判斷自己的服務是否需要 protocol integration test → 判斷原則：什麼時候需要 protocol integration test
• 三層測試如何對應畫面狀態矩陣 → ux-design 模組一：畫面狀態機

三層語意與斷裂點

程式碼和外部服務之間的互動經過三層語意轉換，每一層描述不同粒度的行為。Mock 模擬的是最上層，真實行為發生在下面兩層。

API 層：程式語言的方法簽名

API 層描述的是「這個方法接受什麼參數、回傳什麼型別」。Dart 的 WebSocketSink.add 簽名是 void add(dynamic event) — 從 API 層看，傳 String 和傳 Uint8List 都合法，都不會拋出例外。

FakeWebSocketChannel 忠實實作了這個 API 契約。sink.add("hello") 和 sink.add(Uint8List.fromList([104, 101, 108, 108, 111])) 在 fake 的行為完全相同 — 資料進入內部 buffer，test 可以從 buffer 讀取驗證。Mock 的行為在 API 層是正確的。

協議層：通訊標準的語意規則

協議層描述的是「這個資料在網路上如何被編碼、對方如何解讀」。WebSocket 協議（RFC 6455）定義 text frame 用 opcode 0x1、binary frame 用 opcode 0x2 — 兩者語意不同，接收端可以選擇只處理其中一種。

Dart 的 IOWebSocketChannel（真實實作）根據 sink.add 的參數型別決定 frame type：String 產生 text frame，List<int> 或 Uint8List 產生 binary frame。這個行為是 IOWebSocketChannel 的實作細節，不是 WebSocketSink 介面契約的一部分 — API 簽名用 dynamic 把型別資訊抹除了（T.C1）。

ttyd 只接受 text frame，收到 binary frame 靜默忽略。從 API 層看，sink.add(Uint8List(...)) 合法；從協議層看，這產生了 ttyd 不處理的 binary frame。斷裂點在 API 層和協議層之間 — mock 模擬了前者，但後者的語意差異只有真實 IOWebSocketChannel + 真實 ttyd 才會浮現。

環境層：執行環境的行為差異

環境層描述的是「同一段程式碼在不同執行環境下行為不同」。DNS 解析、TLS 憑證驗證、防火牆規則、作業系統的 socket 實作 — 這些在 test 環境可能和 production 不同。

環境層的遮蔽比協議層更難處理，因為即使用真實服務做 protocol integration test，test 環境和 production 環境仍可能有差異。本模組不深入環境層議題。

遮蔽的兩種模式

Mock 遮蔽在實務上有兩種不同的表現，需要不同的偵測策略。

模式一：功能存在但行為錯誤

程式碼有對應的實作，但實作的行為和真實服務期望的行為不一致。Mock 讓這個不一致變得不可見，因為 mock 接受了實際上外部服務不會接受的輸入。

T.C1 就是這種模式。sendData() 實作了「發送鍵盤輸入」的功能，但發送的是 binary frame 而非 text frame。Mock 的 sink.add(dynamic) 接受 Uint8List 不報錯，真實 ttyd 靜默忽略 binary frame。功能存在，行為錯誤，mock 遮蔽了錯誤。

這種模式的偵測策略是 protocol integration test — 對真實服務發送相同輸入，比對回應是否符合預期。

模式二：功能根本沒實作

程式碼缺少應有的功能步驟，但 mock 不需要這個步驟就能進入成功狀態。Mock 把多步驟的協議流程簡化成單步操作，讓開發者不知道還有缺少的步驟。

T.C2 就是這種模式。ttyd 要求連線後發送 auth token，但 ConnectionManager 沒有實作這個步驟。FakeWebSocketChannel.ready 立即完成不需認證，stream 由開發者手動控制，不依賴 auth 狀態。Mock 把「TCP 握手 → WS 握手 → auth token → 驗證通過 → 推送資料」這個多步驟流程簡化成「ready 完成 → stream 有資料」（T.C2）。

功能缺失比功能錯誤更難被偵測。功能錯誤至少有一段程式碼可以被 test 覆蓋（只是斷言的對象不夠深）；功能缺失意味著沒有程式碼可以寫 test。只有 protocol integration test 對真實服務跑完整流程，才能暴露「應該有但沒有」的步驟。

Mock 不應該模擬協議行為

面對 mock 遮蔽的第一個直覺反應通常是「讓 mock 更逼真」— 在 FakeWebSocketChannel 裡加入 frame type 區分、auth handshake 驗證等邏輯。這個方向有結構性問題。

Mock 的價值在於簡化 — 把複雜的外部依賴替換成行為可預測的替身，讓 unit test 專注在程式碼邏輯。如果 mock 開始模擬協議行為，mock 本身變成需要維護和驗證的複雜元件。Mock 的正確性由誰保證？如果外部服務更新了協議版本，誰負責更新 mock？

更根本的問題是：即使 mock 完美複製了當前版本的協議行為，它仍然是開發者對協議的理解的副本，不是協議本身。如果開發者對協議的理解就有偏差（例如不知道 ttyd 需要 auth token），mock 會忠實複製這個偏差。

正確的分工是：mock 負責 API 層，protocol integration test 負責協議層。每一層用正確的工具驗證。

下一步路由

• 如何辨認偽裝成 integration test 的 mock test → 名義 integration test 的識別與修正
• 判斷自己的服務是否存在這種斷裂 → 判斷原則：什麼時候需要 protocol integration test
• 想看 SDK 自動攔截如何影響 mock 遮蔽 → monitoring 模組三 SDK 設計

辨識特徵

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 → 模組三：協議整合測試

三個判斷維度

維度一：協議複雜度

程式碼和外部服務之間的協議是否存在 API 層無法描述的語意？

HTTP REST API 的協議複雜度相對低：request body 是 JSON、response body 是 JSON、status code 有明確語意。Mock 一個 REST endpoint（回傳固定 JSON）和真實 endpoint 的行為差異主要在效能和邊界案例，核心語意差距小。

WebSocket 協議的複雜度較高：連線握手、frame type（text / binary / ping / pong / close）、分片（fragmentation）、壓縮擴展（permessage-deflate）、子協議協商 — 這些語意在 API 層（sink.add(dynamic)）是不可見的。gRPC 的 streaming、deadline propagation、metadata header 也有類似特徵。

判斷問題：API 簽名是否隱藏了協議層的行為分支？ 如果 API 用 dynamic、Object、Any 等寬泛型別接受輸入，而協議層對不同輸入有不同處理方式，這就是需要 protocol integration test 的訊號。

app_tunnel 的 sink.add(dynamic) 就是這個模式 — API 簽名不區分 String 和 Uint8List，但協議層對兩者產生不同的 frame type（T.C1）。

維度二：Mock 寬鬆度

Mock 的行為是否比真實服務更寬容？

Mock 通常是「最小可用」的實作 — 能讓 test 通過就好。這意味著 mock 的行為往往比真實服務寬鬆：不檢查認證、不限制速率、不要求特定順序、不區分輸入格式。

寬鬆本身不是問題，但寬鬆程度和真實服務的差距決定了 mock 遮蔽的風險大小。判斷問題：Mock 跳過了真實服務的哪些步驟？每個被跳過的步驟在業務上是否關鍵？

app_tunnel 的 FakeWebSocketChannel 跳過了 auth handshake — ready 立即完成不需認證。Auth handshake 在業務上是關鍵步驟（沒有認證，ttyd 不推送資料），mock 跳過這一步讓「功能根本沒實作」變得不可見（T.C2）。

逐項列出 mock 跳過的步驟是一個實用的 audit 方法。寫出「FakeWebSocketChannel 和 IOWebSocketChannel 的行為差異清單」，每一個差異點就是潛在的遮蔽風險。

維度三：失敗靜默度

外部服務收到非預期輸入時，回應是明確的錯誤還是靜默忽略？

如果外部服務對錯誤輸入回傳 HTTP 400 或斷線，問題在實機測試時會快速浮現 — 程式碼進入 error 狀態，開發者看到明確的錯誤訊息。但如果外部服務靜默忽略，問題表現為「連線成功但沒有回應」，debug 方向可能完全錯誤。

ttyd 收到 binary frame 時靜默忽略，不回傳錯誤碼也不斷線。這讓問題的表現從「frame type 錯誤」變成「終端機無回應」，開發者的 debug 方向是「為什麼 terminal 沒反應」而非「為什麼 frame type 不對」。

判斷問題：外部服務是否有靜默忽略的行為？ 如果有，protocol integration test 的價值更高 — 因為即使在實機測試階段，靜默忽略也會增加 debug 成本。

決策流程

以下流程不追求完備覆蓋所有情境，而是提供一個起點，根據上述三個維度的組合判斷 protocol integration test 的必要性。

協議複雜度高（API 層和協議層有語意斷裂）： 需要 protocol integration test。即使 mock 寬鬆度低、失敗回報明確，語意斷裂本身就是 mock 結構性無法覆蓋的盲區。

協議複雜度低，但 mock 寬鬆度高（mock 跳過業務關鍵步驟）： 需要 protocol integration test。Mock 跳過的步驟越多，「功能缺失不可見」的風險越大。

協議複雜度低，mock 寬鬆度低： 依失敗靜默度判斷。如果外部服務靜默忽略錯誤，protocol integration test 有較高價值；如果錯誤回報明確，可以依賴實機測試階段的 error 來發現問題。

成本極低的情境： 當外部服務可以在 test 環境輕鬆啟動時（自用工具 server+client 同機、Docker 一行啟動的 open source service），protocol integration test 的成本門檻大幅降低，三個維度中任何一個有疑慮就值得寫。

下一步路由

• 想實作 protocol integration test → 模組三：協議整合測試
• 理解 mock 遮蔽的結構性原因 → Mock 遮蔽機制分析
• 反模式：試圖用更多 mock test 補救 → 反模式：用 mock 數量彌補 mock 盲區

數量與層級的區別

app_tunnel 的 192 個 unit test 覆蓋了 ConnectionManager、AnsiParser、TerminalBuffer 等元件的邏輯分支。如果在 mock test 全過但實機失敗後，反應是「再寫 50 個 test」，新寫的 test 會使用同一個 FakeWebSocketChannel，測試更多的邏輯分支 — 更多的輸入組合、更多的邊界條件、更多的錯誤處理路徑。

這 50 個新 test 和原來的 192 個 test 在同一個 mock 環境中執行，受到同一個 FakeWebSocketChannel 的行為限制。FakeWebSocketChannel 不區分 text frame 和 binary frame — 這個限制在第 1 個 test 和第 242 個 test 中都一樣。數量增加了，遮蔽範圍沒有改變。

用類比說明：用純水測試淨水器的過濾效果，不管測 1 杯還是 1000 杯，結論都是「水很乾淨」。問題在測試材料 — 需要用含有雜質的水測試才能驗證過濾功能。Mock 是純水，真實服務互動是含雜質的水。

覆蓋率指標的盲點

Line coverage 和 branch coverage 衡量的是「程式碼中有多少行 / 分支被 test 執行過」。這些指標在同一層 test 內有意義 — 100% branch coverage 的 unit test 確保每個 if/else 都被走過。

但覆蓋率指標不區分 test 的依賴環境。一個使用 FakeWebSocketChannel 的 test 和一個使用 IOWebSocketChannel 的 test 走過同一行 sink.add(data) — 在覆蓋率報告中是同一行被覆蓋，但驗證的語意完全不同。

覆蓋率 100% 意味著「在 mock 環境中，所有程式碼分支都被走過」。這不等於「在真實環境中，所有程式碼分支的行為都是正確的」。app_tunnel 的 sendData() 在覆蓋率報告中是「已覆蓋」的，但覆蓋它的 test 用的是不區分 frame type 的 fake。

這個反模式如何在團隊中擴散

「test 不夠多」是一個容易執行、容易衡量的回應。在沒有獨立 QA 驗收流程的團隊中（覆蓋率報告是主要品質指標），寫更多 test 可以提高覆蓋率數字，覆蓋率數字上升給團隊信心。相比之下，「需要一個新的 test 層級」需要建置新的 test 環境、學習不同的 test 技術、接受較慢的執行速度。

這個成本差異讓團隊傾向於在既有的 mock test 層加量，而非引入新的 test 層。每一輪加量後覆蓋率上升，團隊信心增加，但 mock 遮蔽的盲區從未被觸及。問題在下一次實機測試或 production incident 中再次浮現，觸發新一輪的「test 不夠多」反應。

打破這個循環的起點是區分「同層覆蓋率不足」和「層級缺失」。如果問題是同層覆蓋率不足（某個分支沒被 test 走到），加 test 有效。如果問題是層級缺失（mock 結構性地遮蔽了某類行為），加同一層的 test 無效，需要引入新的 test 層級。

判讀訊號

以下訊號指向「層級缺失」而非「數量不足」：

test 全過但實機失敗的 bug 類型集中在外部互動：連線問題、認證問題、資料格式問題、逾時問題 — 這些問題的共同特徵是發生在程式碼與外部服務的邊界上，不是程式碼內部的邏輯錯誤。

修復後原有 test 不需要改動：如果 bug 修復只加了新程式碼（例如新增 auth handshake 步驟）而原有 test 全部不受影響，說明原有 test 從一開始就沒有覆蓋這個行為 — 整個 test 層級不涵蓋這類行為。

bug 修復是型別轉換或編碼調整：if (data is Uint8List) sink.add(String.fromCharCodes(data)) 這類修復改變的是資料在協議層的表現，不是程式邏輯。在 mock 環境中，這個修改前後的行為完全相同 — mock 不區分 frame type。

區分「同層覆蓋率不足」和「層級缺失」之後，回到三層定義與職責表確認每層的邊界。Mock 遮蔽的結構性原因在 Mock 遮蔽機制分析中展開。如果判斷結果是層級缺失，判斷原則：什麼時候需要 protocol integration test 提供引入新層級的決策流程。