決策依據

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 模組三 成本判斷表。

概念位置

Protocol integration test 位在 unit test 和 E2E test 之間。Unit test 用 mock 驗證程式碼邏輯，E2E test 經過 UI 驗證完整流程，protocol integration test 用程式碼直接呼叫 client 端連線函式、對真實服務執行操作。它填補「程式碼邏輯正確但協議互動錯誤」這個 mock 結構性無法覆蓋的空隙。

可觀察訊號與例子

需要 protocol integration test 的訊號是：API 簽名用寬泛型別（dynamic、Object、Any）隱藏了協議層的行為分支、mock 跳過了業務關鍵步驟（認證、握手）、或外部服務對錯誤輸入靜默忽略。WebSocket 的 text/binary frame 差異、gRPC 的 streaming deadline、MQTT 的 QoS level 都是典型場景。

設計責任

Protocol integration test 要決定服務 fixture 的管理方式（Process.start / Docker / testcontainers）、健康檢查策略（port 可達 / HTTP health / 業務操作成功）、和狀態隔離方式（每 test 重啟 / 重設狀態 / 獨立 namespace）。成本判斷依據服務啟動成本和協議複雜度兩個維度。

三種 test 的邊界

Unit test

驗證程式碼邏輯。外部依賴全部用 mock 替代。斷言對象是函式的回傳值、狀態變化、例外拋出。

Unit test 無法驗證的：程式碼和真實外部服務之間的行為差異（mock 遮蔽了這些差異，見 Mock 遮蔽機制分析）。

Protocol integration test

驗證程式碼和真實服務的協議互動。不用 mock — 對真實的服務實例發送請求、觀察真實的回應。不經過 UI — 直接呼叫 client 端的連線函式或 HTTP client。

Protocol integration test 驗證的是：連線能否建立、認證流程是否正確、發送的資料格式是否被接受、回應是否符合預期。

E2E test

驗證完整的使用者操作流程。從 UI 操作開始（點擊按鈕），經過 client 端邏輯，到達真實服務，再回到 UI 顯示結果。

E2E test 的覆蓋範圍最廣但成本最高 — 需要啟動 app、操作 UI、等待網路回應、斷言 UI 狀態。E2E test 通常執行慢、不穩定（UI 動畫、網路延遲、裝置狀態影響結果）。

Protocol integration test 的定位

Protocol integration test 填補 unit test 和 E2E test 之間的空隙。Unit test 覆蓋程式碼邏輯，E2E test 覆蓋端到端流程，protocol integration test 覆蓋「程式碼和外部服務的互動」這個特定層。

這一層的 test 用程式碼直接呼叫 client 端的連線函式（跳過 UI），對真實的服務實例執行操作（跳過 mock），然後斷言服務的回應是否符合協議規格。

以 app_tunnel 為例，一個 protocol integration test 的結構：

11. 啟動本機 ttyd 服務
22. 用 IOWebSocketChannel 連線到 ttyd
33. 發送 auth token JSON frame
44. 斷言收到 terminal output
55. 發送 Uint8List 鍵盤輸入
66. 斷言 ttyd 沒有回應（binary frame 被忽略）
77. 發送 String 鍵盤輸入
88. 斷言 ttyd 有回應（text frame 被處理）

這個 test 不需要 Flutter UI、不需要 FakeWebSocketChannel，直接驗證「我的程式碼送出的資料，真實 ttyd 是否正確處理」。

以 WebSocket 為例的具體實作在 WebSocket 協議測試實作中展開。在投入建置之前，用成本判斷表評估服務啟動成本和協議複雜度是否值得這一層 test。Protocol integration test 和 mock test 的分工邊界回到 testing 模組一 測試策略分層的三層框架。

三層的職責邊界

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 模組一：畫面狀態機

對應 findings

待寫章節

• 三層定義與職責表（從 _index.md 的表格擴展為完整論述）
• Mock 遮蔽機制分析（API 層 vs 協議層 vs 環境層的斷裂點）
• 「名義 integration test」的識別與修正
• 判斷原則：什麼時候需要 protocol integration test（決策表）
• 反模式：用 mock 數量彌補 mock 盲區

跨分類引用

• → monitoring 模組三 SDK 設計：SDK 的自動攔截機制影響哪些錯誤能被 test 覆蓋
• → ux-design 模組一 畫面狀態機：狀態矩陣直接轉成 screen state test case
• ← ux-design 模組二 Gate Fallback：開發環境遮蔽 gate 問題的機制和 mock 遮蔽結構相同
• ← work-log 案例入口：192 個測試全過、實機全壞

要驗證什麼

從 T.C1 和 T.C2 的案例推導出 WebSocket protocol test 至少需要覆蓋的場景：

Frame type 驗證

IOWebSocketChannel 對 String 和 Uint8List 產生不同的 frame type（text vs binary）。ttyd 只接受 text frame，收到 binary frame 靜默忽略（T.C1）。

Protocol test 需要驗證：

• 發送 String → ttyd 回應（text frame 被處理）
• 發送 Uint8List → ttyd 不回應（binary frame 被忽略）
• 確認 sendData() 函式實際發送的是 text frame

Auth handshake 驗證

ttyd 連線後需要發送 auth token JSON frame 完成認證，認證通過後才推送 terminal output（T.C2）。

Protocol test 需要驗證：

• 連線後發送正確的 auth token → 收到 terminal output
• 連線後不發送 auth token → 逾時無 output
• 連線後發送錯誤的 auth token → 連線被斷開或無 output

連線生命週期驗證

WebSocket 連線的建立、維持、斷開在 mock 環境中都是瞬間完成的。真實環境中有延遲、可能失敗、可能逾時。

Protocol test 需要驗證：

• 連線建立的成功路徑（TCP → WS 升級 → ready）
• 連線逾時的行為（server 不可達時 client 的回應）
• 連線斷開後的狀態（stream 是否正確關閉）

Test 結構

 1setUp: 啟動本機 ttyd（Process.start('ttyd', ['bash'])）
 2tearDown: 停止 ttyd（process.kill()）
 3
 4test('text frame is accepted by ttyd'):
 5  channel = IOWebSocketChannel.connect('ws://localhost:7681/ws')
 6  await channel.ready
 7  channel.sink.add('{"AuthToken":"base64(user:pass)"}')
 8  channel.sink.add('echo hello')  // String → text frame
 9  output = await channel.stream.first.timeout(5s)
10  expect(output, contains('hello'))
11
12test('binary frame is silently ignored by ttyd'):
13  channel = IOWebSocketChannel.connect(...)
14  await channel.ready
15  channel.sink.add('{"AuthToken":"..."}')
16  channel.sink.add(Uint8List.fromList(utf8.encode('echo hello')))
17  expect(channel.stream.first.timeout(2s), throwsTimeoutException)
18
19test('auth token required before output'):
20  channel = IOWebSocketChannel.connect(...)
21  await channel.ready
22  // 不發 auth token，直接發指令
23  channel.sink.add('echo hello')
24  expect(channel.stream.first.timeout(2s), throwsTimeoutException)

執行成本

app_tunnel 的 server（ttyd）和 client 在同一台機器上。啟動 ttyd 是一行指令（ttyd bash），不需要 Docker、不需要雲端服務、不需要網路。整個 test suite 的執行時間主要是連線建立和逾時等待，每個 test case 約 2-5 秒。

這個低成本是自用工具的結構優勢 — server 可以在 test 的 setUp 中啟動、tearDown 中停止，不需要共享的 test 環境（本章合成，TF-8 Derive）。

下一步路由

• HTTP 的 contract test 設計 → HTTP contract test 設計
• CI 中的服務管理 → CI 中的服務 fixture 管理
• 什麼時候值得寫 protocol integration test → 成本判斷表

本章目標

學完本章後，你將能夠：

1. 用 httptest.Server 建立真實 WebSocket 測試入口
2. 將 http:// 測試 URL 轉成 ws://
3. 用 deadline 避免 read/write 永久卡住
4. 驗證 subscribe、push、error response 與 cleanup
5. 分辨 integration test 與 unit test 的責任邊界

【觀察】WebSocket 的錯誤常出現在元件交界

WebSocket 測試的核心困難是很多錯誤不在單一函式裡。Router 單元測試可能通過，但真實連線仍可能因為 upgrade path、read pump、write pump、send buffer 或 unregister 流程出錯。

Integration test 適合驗證這些交界：

• client 能否成功 dial 到 /ws
• server 是否接受 client action
• subscribe 後是否收到 acknowledgement
• server broadcast 是否能推到 client
• client 關閉後 hub 是否清理連線
• 錯誤 action 是否回 error message 而不是斷線

這些不是每個單元測試都該覆蓋的內容。Integration test 的價值在於證明多個元件能透過真實協定協作。

【判讀】integration test 補的是協作信心

Integration test 的核心責任是覆蓋協定流程，不是取代所有規則測試。Router validation、topic normalization、dedup key、state transition 應主要用單元測試；WebSocket integration test 只挑關鍵端到端流程。

建議分工：

如果每個 validation case 都啟動 WebSocket server，測試會變慢且失敗定位不清楚。Integration test 應少量、關鍵、穩定。

【執行】用 httptest.Server 建立真實入口

WebSocket integration test 的核心起點是 httptest.Server。它提供真實 HTTP server，不需要手動管理 port。

 1func TestWebSocketSubscribe(t *testing.T) {
 2    server := httptest.NewServer(newRouter())
 3    t.Cleanup(server.Close)
 4
 5    wsURL := "ws" + strings.TrimPrefix(server.URL, "http") + "/ws"
 6
 7    conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil)
 8    if err != nil {
 9        t.Fatalf("dial websocket: %v", err)
10    }
11    t.Cleanup(func() {
12        _ = conn.Close()
13    })
14}

httptest.NewServer 產生的是 http://127.0.0.1:port，WebSocket client 需要 ws://127.0.0.1:port/ws，所以常用字串轉換。

若 handler 需要 hub、router、fake repository，應在測試中明確組裝。這讓 integration test 的依賴可控。

【策略】測試 helper 應封裝連線樣板

Integration test 的核心樣板很多：建立 server、轉 URL、dial、設定 cleanup。可以用 helper 降低重複，但不要把協定斷言藏起來。

 1func newTestWebSocket(t *testing.T, handler http.Handler) (*websocket.Conn, *httptest.Server) {
 2    t.Helper()
 3
 4    server := httptest.NewServer(handler)
 5    t.Cleanup(server.Close)
 6
 7    wsURL := "ws" + strings.TrimPrefix(server.URL, "http") + "/ws"
 8    conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil)
 9    if err != nil {
10        t.Fatalf("dial websocket: %v", err)
11    }
12    t.Cleanup(func() {
13        _ = conn.Close()
14    })
15
16    return conn, server
17}

Helper 負責重複 setup。測試本文仍應清楚寫出「送什麼 message、期待什麼 response」。

【執行】action 測試要檢查協定語意

Action 測試的核心流程是送 client message、讀 server message、檢查協定欄位。

 1func TestSubscribeActionReturnsAcknowledgement(t *testing.T) {
 2    conn, _ := newTestWebSocket(t, newRouter())
 3
 4    request := ClientMessage{
 5        Action: ActionSubscribeTopic,
 6        Data: mustJSON(t, SubscribeTopicRequest{
 7            Topic: "alerts",
 8        }),
 9    }
10
11    if err := conn.WriteJSON(request); err != nil {
12        t.Fatalf("write subscribe: %v", err)
13    }
14
15    response := readServerMessage(t, conn)
16    if response.Type != "topic_subscribed" {
17        t.Fatalf("response type = %q, want topic_subscribed", response.Type)
18    }
19    if response.Topic != "alerts" {
20        t.Fatalf("response topic = %q, want alerts", response.Topic)
21    }
22}

這個測試檢查的是協定語意，不只是連線沒有斷。Subscribe 的成功條件是 server 明確回覆訂閱成功。

【執行】每次讀取前設定 deadline

WebSocket integration test 的核心風險是永久卡住。每次等待 server message 前，都應設定 read deadline。

 1func readServerMessage(t *testing.T, conn *websocket.Conn) ServerMessage {
 2    t.Helper()
 3
 4    if err := conn.SetReadDeadline(time.Now().Add(2 * time.Second)); err != nil {
 5        t.Fatalf("set read deadline: %v", err)
 6    }
 7
 8    var response ServerMessage
 9    if err := conn.ReadJSON(&response); err != nil {
10        t.Fatalf("read server message: %v", err)
11    }
12    return response
13}

Deadline 是測試保護。若 server 沒有送出預期訊息，測試會在合理時間內失敗，而不是卡住整個測試套件。

Timeout 不應過短。CI 可能比本機慢，測試應給足合理緩衝，但仍要能快速暴露失敗。

【執行】推送測試要先建立可觀察觸發點

Server push 的核心測試流程是先讓 client 訂閱 topic，再從 server 端觸發 broadcast，最後讀取 client 收到的 message。

 1func TestSubscribedClientReceivesBroadcast(t *testing.T) {
 2    hub := NewHub()
 3    go hub.Run()
 4
 5    conn, _ := newTestWebSocket(t, newRouterWithHub(hub))
 6
 7    writeClientMessage(t, conn, ClientMessage{
 8        Action: ActionSubscribeTopic,
 9        Data:   mustJSON(t, SubscribeTopicRequest{Topic: "alerts"}),
10    })
11    _ = readServerMessage(t, conn)
12
13    hub.Broadcast("alerts", ServerMessage{
14        Type:  "notification",
15        Topic: "alerts",
16    })
17
18    pushed := readServerMessage(t, conn)
19    if pushed.Type != "notification" {
20        t.Fatalf("pushed type = %q, want notification", pushed.Type)
21    }
22}

這個測試證明 subscribe state、hub broadcast、write pump 能透過真實 connection 協作。若只想測 Broadcast 是否檢查 topic，應寫 hub unit test，不必走 WebSocket。

【策略】非同步清理用 eventually，不用固定 sleep

連線清理測試的核心問題是 cleanup 通常非同步發生。測試應等待可觀察條件，而不是固定 sleep。

 1func eventually(t *testing.T, timeout time.Duration, condition func() bool) {
 2    t.Helper()
 3
 4    deadline := time.Now().Add(timeout)
 5    for time.Now().Before(deadline) {
 6        if condition() {
 7            return
 8        }
 9        time.Sleep(10 * time.Millisecond)
10    }
11
12    t.Fatalf("condition was not met within %s", timeout)
13}

使用方式：

 1func TestClientIsRemovedAfterClose(t *testing.T) {
 2    hub := NewHub()
 3    conn, _ := newTestWebSocket(t, newRouterWithHub(hub))
 4
 5    eventually(t, time.Second, func() bool {
 6        return hub.ClientCount() == 1
 7    })
 8
 9    _ = conn.Close()
10
11    eventually(t, time.Second, func() bool {
12        return hub.ClientCount() == 0
13    })
14}

eventually 不是任意等待；它等待具體條件。失敗時，測試會指出 cleanup 沒發生，而不是把時間耗掉後仍然不清楚原因。

【判讀】error action 應測協定，不只測 log

WebSocket action 失敗的核心語意是單次 action 失敗，不一定代表連線失敗。Integration test 應確認 server 回 error message，並且連線仍可繼續使用。

 1func TestUnknownActionReturnsErrorMessage(t *testing.T) {
 2    conn, _ := newTestWebSocket(t, newRouter())
 3
 4    writeClientMessage(t, conn, ClientMessage{
 5        Action: "unknown_action",
 6    })
 7
 8    response := readServerMessage(t, conn)
 9    if response.Type != "error" {
10        t.Fatalf("response type = %q, want error", response.Type)
11    }
12}

若設計上 unknown action 應直接關閉連線，也應明確測出 close 行為。重點是協定行為要可驗證，不要只依賴 server log。

本章不處理

本章先處理單一 Go server 內的 WebSocket 協定協作；跨節點 fan-out 與壓力測試，會在下列章節再往外延伸：

• Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

這一章承接的是 WebSocket handler、pump 與 heartbeat；如果你要先回看語言教材，可以讀：

• Go：如何新增一個即時訊息 action
• Go：read/write pump 模式
• Go：heartbeat、deadline 與連線清理
• Go：graceful shutdown 與 signal handling
• Go 進階：CI、fuzz、load test 與 chaos testing
• Backend：可靠性驗證流程

小結

WebSocket integration test 應少量覆蓋關鍵端到端協定：dial、送 action、收 response、server push、錯誤回應與 cleanup。測試要使用真實 httptest.Server，每次 read 前設定 deadline，等待非同步清理時使用 eventually。單元測試負責大量規則，integration test 負責證明真實連線能把規則串起來。

辨識特徵

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

HTTP protocol test 的驗證對象

Request 格式

Client 端發送的 request 是否符合 API 規格。Content-Type header、JSON body 的欄位名稱和型別、query parameter 的格式 — 這些在 mock client 中通常不被驗證（mock 接受任何 request），但真實 API 可能因為格式不符而拒絕。

Response 解析

Client 端能否正確解析真實 API 的 response。Mock response 通常是開發者手寫的 JSON，可能和真實 API 的 response 有微妙差異 — 欄位名稱大小寫、數值型別（integer vs float）、null vs 缺失欄位、巢狀結構。

Error response 處理

真實 API 的 error response 格式可能和 success response 不同。Mock client 通常只模擬 success case，偶爾模擬簡化的 error case。真實 API 的 400/401/403/404/500 各自可能有不同的 error body 結構。

認證流程

API 的認證流程（API key、OAuth token、session cookie）在 mock 中通常被跳過。真實 API 的認證包括 token 取得、token 過期、refresh flow — 每一步都可能失敗。

Test 結構

HTTP protocol test 的結構和 WebSocket protocol test 類似 — 對真實 API 發送真實 request、驗證真實 response。

 1test('POST /api/resource creates resource'):
 2  response = await httpClient.post(
 3    'http://localhost:8080/api/resource',
 4    body: jsonEncode({'name': 'test', 'type': 'A'}),
 5    headers: {'Content-Type': 'application/json', 'Authorization': 'Bearer ...'},
 6  )
 7  expect(response.statusCode, 201)
 8  body = jsonDecode(response.body)
 9  expect(body['id'], isNotNull)
10  expect(body['name'], 'test')
11
12test('POST /api/resource with invalid body returns 400'):
13  response = await httpClient.post(
14    'http://localhost:8080/api/resource',
15    body: jsonEncode({'invalid_field': 'value'}),
16    headers: {'Content-Type': 'application/json', 'Authorization': 'Bearer ...'},
17  )
18  expect(response.statusCode, 400)
19  body = jsonDecode(response.body)
20  expect(body['error'], isNotNull)  // 驗證 error body 結構

Consumer-driven contract test

當 client 和 server 由不同團隊開發時，consumer-driven contract test 是 protocol integration test 的延伸。Client 團隊定義「我期望的 request/response 格式」（contract），server 團隊驗證 server 實作是否符合 contract。

Consumer-driven contract test 的工具（Pact、Spring Cloud Contract）自動化了 contract 的定義、驗證和版本管理。適合 API 有多個 consumer 且需要獨立部署的場景。

自用工具或 client/server 同一人開發的場景不需要 contract test 工具 — 直接對真實 server 跑 protocol integration test 更簡單。

下一步路由

• CI 中如何管理 test 用的 server → CI 中的服務 fixture 管理
• WebSocket 的 protocol test → WebSocket 協議測試實作
• 什麼時候用 contract test 替代 protocol integration test → 成本判斷表
• Backend 的 contract testing 實務 → Backend 可靠性 contract testing

概念位置

名義 integration test 在 test 分類中介於 unit test 和真正的 integration test 之間。它的 scope 比 unit test 大（多個內部元件一起測），但驗證對象和 unit test 相同（程式碼內部邏輯）。它和 mock 遮蔽的關係是：名義 integration test 用 mock 替換所有外部依賴，mock 遮蔽了協議層行為，而 test 名稱讓團隊以為這些行為已被驗證。

可觀察訊號與例子

辨識名義 integration test 的三個特徵：核心外部依賴 100% 被 fake 取代、沒有真實的 I/O 操作（網路、檔案、資料庫）、setUp() 不需要啟動外部程序或建立網路連線。

設計責任

修正策略分兩步：改名（讓 test 名稱反映真實驗證對象，如 connection_state_machine_test）和補寫（如果協議互動是關鍵路徑，補寫對真實服務的 protocol integration test）。在 test 檔案頂部標明被 fake 取代的依賴清單，讓後續讀者快速判斷驗證邊界。

對應 findings

待寫章節

• Protocol integration test 定義（跟 unit test / E2E 的邊界）
• WebSocket 協議測試實作（對真實 ttyd 驗證 frame type + auth handshake）
• HTTP contract test 設計
• CI 中的服務 fixture 管理（啟動/停止真實服務的 test harness）
• 成本判斷表：什麼時候值得、什麼時候用 contract test 替代

跨分類引用

• → monitoring 模組三 SDK 設計：SDK 的 transport 行為也需要 protocol test
• ← ux-design 模組三 輸入機制：輸入設計（整行 vs 逐字元）影響 protocol test 的斷言

三種服務管理方案

Process.start（直接啟動程序）

在 test 的 setUp 中用 Process.start 啟動服務程序，tearDown 中用 process.kill 停止。

適合的前提：服務是單一二進位檔（不需要 Docker），啟動速度快（< 2 秒），不需要持久化狀態。

app_tunnel 的 ttyd 就是這個模式。ttyd bash 一行指令啟動，不需要設定檔，不需要資料庫，啟動到可接受連線約 500ms。Test harness 只需要：

1setUp: process = Process.start('ttyd', ['--port', '7681', 'bash'])
2       await waitForPort(7681, timeout: 3s)
3tearDown: process.kill()

Docker Compose

用 Docker Compose 定義服務堆疊，CI 的 before_all 階段 docker compose up，after_all 階段 docker compose down。

適合的前提：服務有依賴（database + cache + app server）、需要特定 OS 環境、需要精確的版本控制。

Docker Compose 的成本是 image pull 時間（首次或 image 更新時）和容器啟動時間。CI 中可以用 image cache 減少 pull 時間，但冷啟動仍比直接啟動程序慢。

Testcontainers

在 test 程式碼中用 testcontainers 套件管理 Docker 容器。每個 test class 或 test suite 啟動自己的容器，test 結束後自動清理。

適合的前提：和 Docker Compose 類似，但需要更細粒度的控制（不同 test 用不同的服務設定），或需要在 test 程式碼中動態決定服務的啟動參數。

Testcontainers 的優勢是 test 和 fixture 在同一個程式碼檔案中，容易理解每個 test 需要什麼環境。缺點是每個 test suite 啟動自己的容器，比共用容器慢。

健康檢查

服務啟動後到可以接受請求之間有延遲。直接在啟動後發送 test request 會因為服務尚未 ready 而失敗。

健康檢查的方式依服務類型而定：

TCP port 可達：waitForPort(port, timeout) 反覆嘗試 TCP 連線，成功即表示服務在監聽。最簡單，適合所有 TCP 服務。

HTTP health endpoint：對 /health 或 /ready 發送 GET request，收到 200 表示服務 ready。比 port check 更可靠 — port 監聽不代表應用層 ready。

特定操作成功：執行一個輕量的業務操作（例如 WebSocket 連線 + 簡單指令），成功表示服務完全 ready。最可靠但最慢。

服務狀態隔離

不同 test 之間的服務狀態需要隔離 — test A 在服務中建立的資料不應該影響 test B。

三種隔離策略：

每 test 重啟服務：最強隔離，最慢。適合服務啟動快（< 1 秒）的場景。

每 test 重設狀態：服務持續運行，test 開始前清理狀態（truncate tables, flush cache）。適合服務啟動慢但重設快的場景。

每 test 用獨立 namespace：服務持續運行，每個 test 使用獨立的 database schema / topic / channel。適合支援多租戶的服務。

app_tunnel 的 ttyd 是無狀態服務（每次連線是獨立的 terminal session），不需要狀態隔離。每個 test 建立新的 WebSocket 連線 = 新的 session。

下一步路由

• 什麼時候值得建 protocol integration test 基礎設施 → 成本判斷表
• Protocol integration test 的定義 → Protocol integration test 定義
• WebSocket 的 protocol test 實作 → WebSocket 協議測試實作

服務啟動成本

服務啟動成本決定了 protocol integration test 的執行成本 — test 跑一次要多久、CI 中佔多少時間。

極低成本（同機單程序）

Server 是一個本機程序，Process.start 一行啟動，不需要 Docker、不需要網路、不需要設定檔。啟動到 ready 不到 2 秒。

app_tunnel 的 ttyd 就是這個場景。ttyd bash 在本機啟動，WebSocket 服務立即可用。整個 protocol integration test suite 的額外成本約 10-15 秒（包含啟動、健康檢查、5 個 test 各 2 秒）（本章合成，TF-8 Derive）。

在這個成本等級下，protocol integration test 幾乎沒有理由不寫。

低成本（Docker 單容器）

Server 用 Docker 容器啟動，需要 pull image（首次或更新時），啟動到 ready 約 5-30 秒。Redis、PostgreSQL、Elasticsearch 等 open source 服務屬於這個等級。

CI 中用 image cache 可以把 pull 時間降到接近零。但容器啟動時間仍比原生程序長。整個 protocol integration test suite 的額外成本約 30-60 秒。

在這個成本等級下，如果協議有任何複雜度（見下方），protocol integration test 值得寫。

中等成本（多容器堆疊）

Server 依賴多個服務（app server + database + cache + message queue），需要 Docker Compose 管理。啟動到所有服務 ready 約 30-120 秒。

Protocol integration test 的執行成本顯著上升。適合在 CI 的獨立 stage 跑（和 unit test 分開），避免拖慢 fast feedback loop。

高成本（外部服務 / SaaS）

Server 是外部 SaaS（Stripe API、AWS S3、第三方 OAuth provider），無法本地啟動。Test 需要打到 sandbox environment，有速率限制和網路延遲。

在這個成本等級下，consumer-driven contract test 可能比 protocol integration test 更實用 — 用 contract 定義期望的 request/response，在本地驗證 client 端行為，不需要每次都打到外部服務。

協議複雜度

協議複雜度決定了 mock 遮蔽的風險大小 — 風險越大，protocol integration test 的價值越高。

高複雜度：WebSocket（frame type、handshake、子協議）、gRPC（streaming、deadline、metadata）、MQTT（QoS level、retain、will message）。API 簽名隱藏了協議層的行為分支，mock 結構性地無法覆蓋。

中複雜度：HTTP REST API（多種 status code、error body 格式、認證流程、分頁）。核心語意（JSON request/response）差距小，但 edge case（error response 格式、header 要求）仍可能被 mock 遮蔽。

低複雜度：本地 IPC（Unix socket、named pipe）、標準格式的檔案讀寫。協議行為簡單，mock 和真實行為差距小。

判斷矩陣

「可選」代表 protocol integration test 有價值但不是必要 — 實機測試階段的手動驗證可能足夠。「實機測試替代」代表成本太高或收益太低，依賴實機測試階段的人工驗證。

成本和複雜度的評估結果決定了要建什麼等級的 test 基礎設施。Protocol integration test 定義提供這一層 test 的精確邊界，testing 模組一的判斷原則從 mock 遮蔽角度補充另一個判斷維度。決定要建之後，CI 中的服務 fixture 管理處理啟動和停止真實服務的工程問題。

本模組承接前面的並發、WebSocket 與架構邊界：時間注入讓狀態轉移可測，WebSocket integration test 驗證真實連線互動，race detector 檢查共享狀態，table-driven test 幫助案例保持清楚。

章節列表

本模組使用的範例主題

本模組使用虛構的即時通知服務作為範例。範例包含 job 狀態轉移、WebSocket subscribe flow、client cleanup、repository concurrent access 與 topic normalization。

範例只用來展示 Go 測試設計，不假設讀者正在維護任何特定專案。

本模組的 Go 核心概念

• 用 now time.Time 或 func() time.Time 控制時間。
• 用 httptest.Server 建立真實 WebSocket integration test。
• 用 read/write deadline 避免測試永久卡住。
• 用 eventually helper 等待非同步清理，而不是固定 sleep。
• 用 go test -race ./... 檢查執行到的 data race。
• 用小而清楚的 table-driven test 表達同一個行為的多組案例。

學習重點

學完本模組後，你應該能判斷：

1. 哪些邏輯應該用純函式測，哪些需要 integration test
2. 測試裡的時間應該如何注入，而不是等待真實時間
3. WebSocket 測試如何避免永久卡住
4. race detector 能找什麼，不能證明什麼
5. table-driven test 何時該拆成多個測試

本模組不處理

本模組不建立完整測試框架，也不討論大型 CI 平台、壓力測試或 chaos testing。這些主題很重要，但本模組先聚焦單一 Go 服務內最常見、最容易失控的可靠性測試；後續可接 CI、fuzz、load test 與 chaos testing。

學習時間

預計 3-4 小時

192 個 unit test 全綠、實機部署後全部功能壞掉。

這不是測試寫得差 — 每個 test 都有明確斷言、覆蓋了正常和錯誤路徑。問題出在測試策略的結構：所有 test 都用 FakeWebSocketChannel 替代真實 WebSocket，永遠不會觸碰真實協議行為。結果是 mock 和真實服務之間的差異，在整個測試套件中完全不可見。

本文拆解三個被 mock 遮蔽的真實問題、分析 mock 遮蔽的機制、提出三層測試策略作為防護。

三個被 Mock 遮蔽的真實問題

問題 1：text frame vs binary frame

ttyd 的 WebSocket 協議期望 text frame，Flutter 的 WebSocketChannel.sink.add(Uint8List) 預設發送 binary frame。兩者在 WebSocket 協議層是不同的 opcode（0x1 text vs 0x2 binary），ttyd 收到 binary frame 會靜默忽略。

 1// 原始寫法 — Uint8List 走 binary frame，ttyd 靜默忽略
 2void sendData(dynamic data) {
 3  _channel!.sink.add(data); // data 是 Uint8List → binary frame
 4}
 5
 6// 修正 — 轉成 String 走 text frame
 7void sendData(dynamic data) {
 8  if (data is Uint8List) {
 9    _channel!.sink.add(String.fromCharCodes(data)); // text frame
10  } else {
11    _channel!.sink.add(data);
12  }
13}

為什麼 mock 抓不到：FakeWebSocketChannel 的 sink.add 接受 dynamic，不區分 String 和 Uint8List，兩者都直接存入 _sinkItems list。Mock 層沒有 frame type 的概念 — 它模擬的是 Dart API，不是 WebSocket 協議。

問題 2：auth token handshake 缺失

ttyd 連線後需要發送一個 auth token JSON frame 完成認證，否則 ttyd 關閉連線。整個 auth handshake 的邏輯根本沒實作，因為 FakeWebSocketChannel 不需要認證就能「連線成功」。

 1// 缺失的 auth handshake — 連線建立後需發送
 2void _sendAuthTokenIfNeeded(Credential credential) {
 3  final token = base64Encode(
 4    utf8.encode('${credential.ttydUser}:${credential.ttydPass}'),
 5  );
 6  final frame = _protocol.buildAuthTokenFrame(authToken: token);
 7  if (frame != null) {
 8    _channel!.sink.add(frame);
 9  }
10}

為什麼 mock 抓不到：FakeWebSocketChannel 的 ready 立即完成、stream 立即可用。真實 ttyd 需要收到正確的 auth token 才會開始推送 terminal output；mock 不需要，所以 test 永遠看到「連線成功」。

問題 3：ANSI 控制序列多樣性

真實 shell 輸出包含 OSC 序列（ESC]...BEL 終端機標題設定）、CSI private mode（ESC[?...h/l 游標隱藏、括號貼上模式）等控制序列。ANSI parser 只處理基本 SGR 色彩碼，其他序列全部殘留在輸出中顯示為亂碼。

為什麼 mock 抓不到：test 的輸入資料是手寫的乾淨 ANSI 字串（如 \x1B[31mred\x1B[0m），不包含真實 shell 會產生的 OSC/CSI private mode 序列。真實 zsh prompt 一打開就送幾十種控制序列，但 test data 是人工挑選的乾淨子集。

Mock 遮蔽的機制

三個問題有共同的結構：

共同模式：mock 忠實模擬了 Dart API 的行為契約，但 Dart API 和真實服務之間還有一層協議語意（WebSocket frame type、ttyd auth handshake、shell 完整輸出），mock 把這層完全跳過了。

這是 mock 的本質。Mock 的職責是讓 unit test 快速、確定性、不依賴外部服務。但當被測元件的正確性取決於「與外部服務的協議契約」時，mock 從結構上就無法驗證這件事。

三層測試策略

Unit test（已有，保留）

用 FakeWebSocketChannel 驗證 ConnectionManager 的狀態機：idle → connecting → connected → disconnected，錯誤處理路徑（biometric 失敗、credential 缺失、timeout）。192 個 test 全部保留。

Protocol integration test（新增）

對真實 ttyd + proxy 驗證 WebSocket 協議契約。 這一層的關鍵是：不用 mock，直接連真實服務。

 1// 概念示例 — 對真實 ttyd 驗證協議
 2test('auth token handshake succeeds against real ttyd', () async {
 3  // 前提：本機 ttyd 已啟動（test fixture 或 CI 腳本啟動）
 4  final channel = IOWebSocketChannel.connect(
 5    Uri.parse('ws://127.0.0.1:7681/ws'),
 6    protocols: ['tty'],
 7  );
 8  await channel.ready;
 9
10  // 發送 auth token
11  final token = base64Encode(utf8.encode('testuser:testpass'));
12  channel.sink.add('{"AuthToken":"$token"}');
13
14  // 驗證收到 terminal output（text frame，prefix '0'）
15  final firstFrame = await channel.stream.first;
16  expect(firstFrame, isA<String>()); // text frame, not binary
17  expect(firstFrame[0], '0');        // ttyd output prefix
18});

為什麼這層成本低：ttyd 和 proxy 都在本機，ttyd --port 7681 --credential "test:test" /bin/echo hello 一行就能啟動一個最小測試服務。CI 腳本先啟動 ttyd → 跑 Dart integration test → 停止 ttyd。不需要模擬器、不需要真實手機。

Screen state test（補強）

Widget test 覆蓋所有畫面狀態的 UI 行為：每個狀態顯示什麼 widget、哪些按鈕可按、按了之後導航到哪裡。這層已有 7 個 test，但不覆蓋 back 按鈕和 text input。

判斷原則：什麼時候需要 protocol integration test

不是所有專案都需要三層。判斷標準：

app_tunnel 的特殊優勢：server 和 client 都在同一台機器上。啟動 ttyd + proxy 然後跑 Dart test，成本極低但價值極高 — 三個實機問題中的兩個（text/binary frame、auth handshake）都能在這層直接抓到。

反模式：用 mock 數量彌補 mock 盲區

「192 個 test 全過」給了虛假的信心。常見的反應是「測試不夠多」然後再加更多 mock test，但問題在層級覆蓋 — 300 個用同一個 FakeWebSocketChannel 的 test 仍然抓不到 text vs binary frame。

測試策略的品質用層級覆蓋衡量，而非數量。 一個對真實 ttyd 的 5 行 protocol test，比 50 個新增的 mock test 更能防止實機部署失敗。

延伸閱讀

本文的觀察和判讀在 Testing 測試策略 教學系列中展開為系統性的教學模組：三層定義與職責表、Mock 遮蔽機制分析、Protocol integration test。