觀察

app_tunnel Flutter app 連接 ttyd WebSocket 終端機。ConnectionManager.sendData() 接收 Uint8List 型別的鍵盤輸入，直接傳給 _channel!.sink.add(data)。Dart 的 IOWebSocketChannel 對 Uint8List 發送 binary frame（opcode 0x2），ttyd 期望 text frame（opcode 0x1），收到 binary frame 靜默忽略。

判讀

1. Mock 模擬的是 Dart API 契約，不是 WebSocket 協議契約。FakeWebSocketChannel 忠實實作了 WebSocketChannel 的 Dart interface — sink.add(dynamic) 接受任何型別。但 IOWebSocketChannel 的 sink.add 實際行為是：String → text frame，List<int> / Uint8List → binary frame。Mock 沒有也不應該模擬這個協議層行為。

2. ttyd 的靜默忽略放大了問題。如果 ttyd 對 binary frame 回傳錯誤碼或斷線，app 至少會進入 error 狀態讓開發者察覺。靜默忽略讓問題從「連線失敗」變成「連線成功但無回應」，debug 方向完全錯誤。

3. 型別系統幫不上忙。Dart 的 WebSocketSink.add 簽名是 void add(dynamic event) — dynamic 吃掉了型別資訊。即使用強型別語言，如果 API 設計成 dynamic，型別檢查無法區分協議語意。

策略

1. Protocol integration test：對真實 ttyd 發送 Uint8List 和 String，斷言兩者行為差異。一個 5 行 test 就能抓到這個問題。
2. 在 sendData 層做型別轉換：不依賴下游 channel 的行為，在自己的 API 邊界確保型別正確。
3. Log 送出的 frame type：developer.log('WS send: type=${data.runtimeType}') 讓 debug 時立即可見。

下一步路由

• 想寫 protocol integration test → 模組三：協議整合測試
• 想理解 mock 遮蔽的系統性機制 → Mock 遮蔽機制分析
• 類似案例（auth handshake） → T.C2 Auth handshake 缺失

觀察

ttyd WebSocket 協議要求連線建立後發送一個 JSON frame 包含 base64 編碼的帳密（{"AuthToken":"base64(user:pass)"}），ttyd 驗證通過後才開始推送 terminal output。app_tunnel 的 ConnectionManager 建立 WS 連線後直接開始監聽 stream，沒有發送 auth token。

判讀

1. Mock 的 happy path 比真實服務寬鬆。FakeWebSocketChannel 的 ready 是 Future.value()（立即完成），stream 是開發者手動控制的 StreamController。真實 ttyd 的行為是：ready 完成代表 TCP+WS 握手成功，但 stream 要等 auth token 驗證後才有資料。Mock 把兩步合成一步。

2. Integration test 名為整合實為 fake。connection_flow_test.dart 標題是「端對端整合測試」，但內部使用 FakeWebSocketChannel + FakeBiometricService + InMemoryCredentialRepository — 三個核心依賴全是 fake。這個 test 驗證的是「假設所有外部服務都正常，內部狀態機是否正確」，不是「真實服務互動是否正確」。

3. 功能缺失比功能錯誤更難被 test 抓到。功能錯誤（T.C1 text vs binary）至少有一個實作可以斷言；功能缺失意味著沒有程式碼可以 test。只有 protocol integration test（對真實服務跑）才能暴露「應該有但沒有」的行為。

策略

1. Protocol integration test 必須涵蓋 auth handshake：連線 → 發送正確 auth token → 斷言收到 output；連線 → 不發送 auth token → 斷言 timeout 或斷線。
2. 在企劃階段列出協議握手步驟：ttyd WS 協議的 auth handshake 應該在 spec 文件中明確列出，不依賴開發者記得實作。
3. 區分「名義 integration」和「真實 integration」：test 名稱含 integration 但全用 fake，應標明 fake-integration 或改名 connection-state-machine-test。

下一步路由

• 想區分 mock 層級 → 模組一：測試策略分層
• 想建 protocol integration test → 模組三：協議整合測試
• 想設計 auth 機制的 UX fallback → U.C2 biometricOnly 無 fallback

三個判斷維度

維度一：協議複雜度

程式碼和外部服務之間的協議是否存在 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 盲區