隱性假設如何產生

開發者設計 connected 狀態時，注意力在「終端機介面的功能」— 打字、特殊鍵、滾動。「使用者可能想離開 connected 狀態回到首頁」這個需求在 happy path 中不存在 — 如果一切順利，使用者為什麼要離開？

這個推論在使用者行為和開發者假設吻合時成立。但使用者可能想：

• 切換到配對畫面重新配對另一台裝置
• 暫時離開終端機處理其他事
• 遇到回應異常想從頭重新連線
• 覺得功能不符需求想回到首頁看其他選項

app_tunnel 的 Terminal 畫面五個狀態都沒有退出路徑。connected 狀態有打字和特殊鍵操作，但沒有「離開」操作；error 和 disconnected 有重連按鈕，但沒有「放棄重連、回首頁」的選項。開發者設計 error 狀態時的隱性假設是「使用者遇到錯誤會想重試」— 沒考慮「使用者可能想放棄」（U.C1）。

Happy path 偏差的擴散

Happy path 偏差不只發生在單一畫面。首頁只放 Connect Terminal 按鈕、沒放配對入口，是首頁層級的 happy path 偏差 — 假設使用者已經完成配對、只需要連線（U.C4）。

操作盤點的「前端引導」只描述顯示不描述操作和退出，是設計流程層級的 happy path 偏差 — 關注「順利時使用者看到什麼」，忽略「不順利時使用者能做什麼」。

從企劃到設計到實作，每一層的 happy path 偏差累積起來，最終產出的 app 在正常情境下運作良好，在任何偏離的情境下使用者都被困住。

用狀態矩陣防止

畫面狀態矩陣的四欄結構（顯示 / 可用操作 / 進入條件 / 退出路徑）強制設計者回答每個狀態的操作和退出問題。不需要預測使用者的所有行為，只需要機械式地對每個狀態填寫四欄 — 空白格自動暴露缺口。

具體的檢查規則：

退出路徑欄為空：需要補退出路徑。即使是 connecting 這種過渡狀態，使用者也應該能取消。

可用操作欄只有一個選項：使用者在這個狀態下只有一條路。如果這條路走不通（重連失敗），使用者被困住。至少考慮加一條替代路徑（返回、取消）。

進入條件是不可逆的：使用者無法自行觸發進入條件的反向操作（例如「連線成功」的反向操作「斷開連線」不存在）。這代表使用者進入後無法主動退出，只能等系統狀態變化。

狀態矩陣的價值在於機械式的完整性檢查。填完所有狀態的四欄是一個 10 分鐘的工作（以 5 個狀態的畫面為例），產出是一張可以直接轉為 test case 的表格，同時能在實作前發現所有退出路徑缺口。

矩陣的四欄定義和填寫步驟在畫面狀態矩陣的定義與填寫方法中完整展開。如果畫面設計從 BDD 操作盤點出發，從 BDD 操作盤點展開到狀態矩陣提供五步驟的展開流程。填完的矩陣可以直接轉成 widget test case — 具體方法見 testing 模組四 UI 自動化。

數量與層級的區別

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 提供引入新層級的決策流程。