決策依據

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 模組一 測試策略分層的三層框架。

觀察

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 缺失

從矩陣到 test case 的轉換規則

每個狀態至少一個 test case

矩陣中的每一行代表畫面的一個狀態。每個狀態產生一個 test case，驗證三件事：

1. 該狀態下的顯示元素是否存在
2. 該狀態下的可用操作是否可觸發
3. 該狀態下的退出路徑是否可到達

以 app_tunnel Terminal 畫面為例，五個狀態產生五個 test case：

 1testWidgets('idle state shows blank and allows cancel', (tester) async {
 2  await tester.pumpWidget(terminalScreen(state: idle));
 3  expect(find.byType(CircularProgressIndicator), findsNothing);
 4  expect(find.byKey(Key('cancel_button')), findsOneWidget);
 5});
 6
 7testWidgets('error state shows message, retry, and back', (tester) async {
 8  await tester.pumpWidget(terminalScreen(state: error));
 9  expect(find.text('連線失敗'), findsOneWidget);
10  expect(find.byKey(Key('retry_button')), findsOneWidget);
11  expect(find.byKey(Key('back_button')), findsOneWidget);
12});

退出路徑是獨立的斷言

退出路徑驗證的是「使用者能否離開當前狀態」。斷言方式是 tap 退出按鈕後驗證導航是否發生：

1testWidgets('error state back button navigates to home', (tester) async {
2  await tester.pumpWidget(terminalScreen(state: error));
3  await tester.tap(find.byKey(Key('back_button')));
4  await tester.pumpAndSettle();
5  expect(find.byType(HomeScreen), findsOneWidget);
6});

矩陣中退出路徑為空的狀態 = 沒有退出路徑的 test case = UX 死胡同。如果在填寫 test case 時發現某個狀態沒有退出路徑可以斷言，這本身就是設計缺口的發現。

覆蓋率的衡量

Widget test 的狀態覆蓋率 = 有 test case 的狀態數 / 矩陣中的總狀態數。100% 代表矩陣中每個狀態都有對應的 test case。

狀態覆蓋率和 line coverage 衡量不同的東西。Line coverage 衡量「程式碼中有多少行被執行過」，狀態覆蓋率衡量「設計中有多少狀態被驗證過」。一個狀態的 test case 可能覆蓋很少的程式碼行（只驗證特定狀態下的 UI），但確認了該狀態的設計意圖被正確實作。

狀態轉換的 test

除了靜態狀態的驗證，狀態之間的轉換也需要 test。矩陣的「進入條件」欄定義了觸發轉換的事件。

1testWidgets('connecting transitions to connected on ws success', (tester) async {
2  await tester.pumpWidget(terminalScreen(state: connecting));
3  // 模擬 WebSocket 連線成功
4  connectionManager.emit(ConnectionState.connected);
5  await tester.pumpAndSettle();
6  expect(find.byType(TerminalView), findsOneWidget);
7});

狀態轉換 test 的數量 = 矩陣中的狀態轉換邊數。五個狀態的畫面可能有 8-12 條轉換邊，每條邊一個 test case。

狀態覆蓋和轉換覆蓋確認畫面的邏輯正確性後，導航路徑 test 進一步驗證 back 按鈕和 route 可達性。矩陣本身的填寫方法和四欄定義見 ux-design 模組一 畫面狀態矩陣。如果需要在視覺層面確認 UI 呈現的一致性，螢幕截圖比對提供 visual regression 的實作方式。

連線生命週期 log

連線生命週期 log 記錄的是「流程走到第幾步、每步成功或失敗」。這一層的 log 粒度是步驟級 — 不記錄每一個封包或每一次函式呼叫，只記錄流程中的關鍵節點。

以 app_tunnel 的連線流程為例，連線生命週期包含五步：biometric 認證 → credential 讀取 → WebSocket 連線 → auth token 發送 → stream 訂閱。每步完成時記一條 log，失敗時記一條包含原因的 log。

1[conn] Step 1/5: biometric auth completed (duration: 320ms)
2[conn] Step 2/5: credential loaded (user: admin)
3[conn] Step 3/5: WebSocket connected (url: wss://...)
4[conn] Step 4/5: auth token sent
5[conn] Step 5/5: stream subscribed, ready

app_tunnel 在實機測試前六個核心元件中只有兩個有 log，且全是 W2 修復時事後補上的（T.C4）。W2-002 auth token 問題的 debug 過程中，開發者無法從任何 log 判斷失敗發生在五步中的哪一步。如果有連線生命週期 log，第一次連線就能看到「Step 3 完成，Step 4 未執行」— 直接定位到 auth token 缺失。

連線生命週期 log 在所有模式（debug 和 release）都應該啟用。這層 log 量小（每次連線 5-10 條），不影響效能，但在 production 問題回報時是第一手資訊來源。

Protocol 訊息 log

Protocol 訊息 log 記錄的是通訊協議層面的細節：發送和接收的 frame type、payload 前綴、handshake 參數、逾時值。這一層的粒度比連線生命週期更細 — 每一次 send/receive 都記錄。

1[proto] TX: text frame, payload: {"AuthToken":"base64..."} (42 bytes)
2[proto] RX: text frame, payload prefix: "0" (output data, 128 bytes)
3[proto] TX: binary frame, payload: [72, 101, 108, 108, 111] (5 bytes)

Protocol log 在 debug 時幫助確認「程式碼發送了什麼、收到了什麼」。app_tunnel 的 text/binary frame 問題（T.C1）如果有 protocol log，開發者會在 log 中看到 TX: binary frame 而非預期的 TX: text frame — 直接指向 frame type 問題。

Protocol log 在 release mode 應該能關閉。這層 log 量大（每次鍵盤輸入一條），且 payload 可能包含敏感資訊。Debug mode 預設啟用，release mode 提供開關（例如隱藏設定頁的 toggle）讓進階使用者在回報問題時開啟。

使用者行為 log

使用者行為 log 記錄的是使用者在 UI 上的操作：按鈕點擊、畫面切換、設定變更。這層 log 的粒度是操作級 — 使用者做了一個有意義的動作記一條。

1[ui] screen: HomeScreen, action: tap Connect Terminal
2[ui] screen: TerminalScreen, state: connecting → connected
3[ui] screen: TerminalScreen, action: tap back button
4[ui] screen: HomeScreen, state: returned from terminal

使用者行為 log 在兩個場景有價值：第一，debug 時還原使用者操作路徑 — 「使用者做了什麼導致問題出現」；第二，結合狀態矩陣（ux-design 模組一）做狀態轉換的實際覆蓋率分析 — 哪些狀態轉換在真實使用中經常發生，哪些從未發生。

使用者行為 log 在 release mode 啟用時需要注意隱私。記錄「使用者切換了畫面」是合理的；記錄「使用者輸入了密碼 abc123」需要 redaction 機制（monitoring 模組七 資安）。

三層的關係

三層 log 各自獨立運作，debug 時通常按照從粗到細的順序使用。

粗篩：先看連線生命週期 log，確認流程走到哪一步。如果 Step 3 失敗，問題在 WebSocket 連線層。

細查：切到 protocol 訊息 log，看 Step 3 的連線嘗試中發送和接收了什麼。如果看到 binary frame 發送但沒有回應，問題可能在 frame type。

還原：如果問題和使用者操作有關（例如只在特定操作順序下觸發），看使用者行為 log，還原操作路徑。

三層 log 用同一個時間戳和 correlation ID（例如連線 session ID），讓跨層比對可行。

下一步路由

• 在功能規格中定義 log 點 → 功能規格中的 log 點定義方法
• 事後補 log 和設計產物 log 的品質差異 → 「事後補 log」vs「設計產物 log」的品質差異
• Log 收集方案選擇 → 自架 log endpoint vs 商業方案
• 事件分類與收集策略 → monitoring 模組一 監控心智模型

三層的職責邊界

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 個測試全過、實機全壞

本章目標

學完本章後，你將能夠：

1. 用 now time.Time 測試純狀態轉移
2. 用 func() time.Time 注入長生命週期元件的時間來源
3. 用 table-driven test 覆蓋時間邊界
4. 把 ticker 排程與單次工作拆開測
5. 避免 time.Sleep 造成慢且不穩定的測試

【觀察】直接呼叫 time.Now 會讓測試失去控制

時間相關邏輯的核心問題是同一筆資料在不同時間會得到不同結果。若函式內部直接呼叫 time.Now()，測試就無法完整控制輸入。

反模式：

1func Status(job Job) string {
2    if job.FinishedAt != nil {
3        return "completed"
4    }
5    if time.Since(job.StartedAt) > 5*time.Minute {
6        return "idle"
7    }
8    return "active"
9}

這個函式看起來簡單，但測試無法指定「現在剛好是開始後 4 分鐘」或「現在剛好跨過 5 分鐘」。測試只能依賴真實時間，結果慢且不穩定。

【判讀】時間是狀態轉移的輸入

時間測試的核心判讀是：如果時間會影響結果，時間就是輸入。把 now 放進函式簽名，會讓狀態轉移規則變得可測。

 1type Job struct {
 2    StartedAt  time.Time
 3    FinishedAt *time.Time
 4}
 5
 6func Status(now time.Time, job Job) string {
 7    if job.FinishedAt != nil {
 8        return "completed"
 9    }
10
11    if now.Sub(job.StartedAt) > 5*time.Minute {
12        return "idle"
13    }
14
15    return "active"
16}

now 是明確輸入，因此測試可以建立任何時間點。這也讓讀者一眼看出 Status 看的是 Job 與目前時間的關係。

【執行】用 table-driven test 描述時間邊界

時間邊界的核心測試方式是列出切換點前後的案例。狀態通常在某個 duration 前後改變，table-driven test 能讓這些情境集中呈現。

 1func TestStatus(t *testing.T) {
 2    startedAt := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 3
 4    tests := []struct {
 5        name string
 6        now  time.Time
 7        job  Job
 8        want string
 9    }{
10        {
11            name: "active before idle threshold",
12            now:  startedAt.Add(4 * time.Minute),
13            job:  Job{StartedAt: startedAt},
14            want: "active",
15        },
16        {
17            name: "idle after threshold",
18            now:  startedAt.Add(6 * time.Minute),
19            job:  Job{StartedAt: startedAt},
20            want: "idle",
21        },
22        {
23            name: "completed ignores idle threshold",
24            now:  startedAt.Add(30 * time.Minute),
25            job: Job{
26                StartedAt:  startedAt,
27                FinishedAt: ptrTime(startedAt.Add(2 * time.Minute)),
28            },
29            want: "completed",
30        },
31    }
32
33    for _, tt := range tests {
34        t.Run(tt.name, func(t *testing.T) {
35            got := Status(tt.now, tt.job)
36            if got != tt.want {
37                t.Fatalf("Status() = %q, want %q", got, tt.want)
38            }
39        })
40    }
41}

這個測試不需要 time.Sleep。案例名稱直接描述時間邊界，失敗時能快速定位是哪個規則壞了。

【策略】長生命週期元件用 time provider

Time provider 的核心用途是讓元件在多個方法中取得時間，但測試仍能控制時間來源。最輕量的形式是 func() time.Time。

 1type Monitor struct {
 2    now func() time.Time
 3}
 4
 5func NewMonitor(now func() time.Time) Monitor {
 6    if now == nil {
 7        now = time.Now
 8    }
 9    return Monitor{now: now}
10}
11
12func (m Monitor) Snapshot(job Job) string {
13    return Status(m.now(), job)
14}

測試提供固定時間：

 1func TestMonitorSnapshot(t *testing.T) {
 2    fixedNow := time.Date(2026, 4, 22, 10, 10, 0, 0, time.UTC)
 3    monitor := NewMonitor(func() time.Time {
 4        return fixedNow
 5    })
 6
 7    got := monitor.Snapshot(Job{
 8        StartedAt: fixedNow.Add(-10 * time.Minute),
 9    })
10    if got != "idle" {
11        t.Fatalf("snapshot = %q, want idle", got)
12    }
13}

這比導入大型 clock framework 更輕量，也比在測試裡等待真實時間更可靠。若整個專案有大量時間需求，再考慮統一 clock interface。

【判讀】Ticker 測試要拆排程與工作

Ticker 的核心問題是它同時包含「何時觸發」與「觸發時做什麼」。測試時應把單次工作抽出來，避免為了測狀態規則而等待 ticker。

 1type Worker struct {
 2    syncOnce func(context.Context) error
 3}
 4
 5func (w Worker) Run(ctx context.Context, interval time.Duration) error {
 6    ticker := time.NewTicker(interval)
 7    defer ticker.Stop()
 8
 9    for {
10        select {
11        case <-ctx.Done():
12            return ctx.Err()
13        case <-ticker.C:
14            if err := w.SyncOnce(ctx); err != nil {
15                return err
16            }
17        }
18    }
19}
20
21func (w Worker) SyncOnce(ctx context.Context) error {
22    return w.syncOnce(ctx)
23}

SyncOnce 可以單獨測規則，Run 只需要少數測試確認 context 取消與 ticker 排程。不要讓每個狀態測試都真的啟動 ticker。

【測試】Run 測試應用 context 控制退出

長生命週期 worker 的測試核心是讓退出條件可控。若只想測 context 取消，先取消 context 再呼叫 Run。

 1func TestRunStopsWhenContextCanceled(t *testing.T) {
 2    ctx, cancel := context.WithCancel(context.Background())
 3    cancel()
 4
 5    worker := Worker{
 6        syncOnce: func(context.Context) error {
 7            t.Fatalf("syncOnce should not be called")
 8            return nil
 9        },
10    }
11
12    err := worker.Run(ctx, time.Hour)
13    if !errors.Is(err, context.Canceled) {
14        t.Fatalf("Run() error = %v, want context canceled", err)
15    }
16}

這個測試不需要等待一小時。time.Hour 只是確保 ticker 不會在測試中自然觸發，真正的退出由 context 控制。

【判讀】sleep-based test 應該是例外

Sleep-based test 的核心問題是慢、不穩定、難以定位。排程、CI 負載與機器速度都可能讓測試偶發失敗。

反模式：

1func TestStatusWithSleep(t *testing.T) {
2    start := time.Now()
3    time.Sleep(6 * time.Minute)
4    got := Status(time.Now(), Job{StartedAt: start})
5    _ = got
6}

這種測試不應存在。它拖慢測試套件，仍然不能保證結果穩定。正確做法是直接建構 now 與 StartedAt。

若真的要等待非同步事件，應使用 deadline 與條件重試，而不是固定 sleep；下一章的 integration test 會使用這個原則。

本章不處理

本章先處理時間作為輸入的可測性；更完整的 fake clock 與平台 timeout 合約，會在下列章節再往外延伸：

• Go 進階：heartbeat、deadline 與連線清理

和 Go 教材的關係

這一章承接的是 defer、select loop 與 timeout 邊界；如果你要先回看語言教材，可以讀：

• Go：defer 與資源清理
• Go：select：同時等待多種事件
• Go：如何新增背景工作流程
• Go：graceful shutdown 與 signal handling
• Go 進階：graceful shutdown 與 signal handling
• Go 進階：Kubernetes、systemd 與 load balancer 合約

小結

時間控制測試的重點是把時間變成可指定輸入。純邏輯用 now time.Time，長生命週期元件用 func() time.Time，ticker 排程和單次工作分開測。避免 time.Sleep，測試才會快速、穩定且可重現。

本章目標

學完本章後，你將能夠：

1. 辨識 handler 過重的訊號
2. 把 request DTO 與 command 分開
3. 把業務規則搬到 usecase
4. 讓 handler 只做 request/response 轉換
5. 分開撰寫 usecase test、handler test 與少量 integration test

【觀察】過重 handler 會混合三種責任

handler 過重的核心問題是 transport、application 與 state concern 混在同一個函式。當一個 handler 同時解析 JSON、驗證欄位、檢查重複、修改 map、組 response，它就很難測，也很難重用。

常見壞味道：

• handler 超過一兩個螢幕。
• 測試核心規則必須透過 HTTP。
• JSON tag 出現在 domain type 上。
• handler 直接改 repository 的 map 或 slice。
• 多個 handler 重複同樣的驗證與錯誤 mapping。
• 想新增 CLI、worker 或 WebSocket action 時，只能複製 handler 內的邏輯。

以下是一個過重的建立通知 handler：

 1var notifications = map[string]Notification{}
 2
 3func handleCreateNotification(w http.ResponseWriter, r *http.Request) {
 4    if r.Method != http.MethodPost {
 5        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 6        return
 7    }
 8
 9    var req struct {
10        ID    string `json:"id"`
11        Topic string `json:"topic"`
12        Title string `json:"title"`
13    }
14    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
15        http.Error(w, "invalid json", http.StatusBadRequest)
16        return
17    }
18
19    if strings.TrimSpace(req.ID) == "" || strings.TrimSpace(req.Topic) == "" {
20        http.Error(w, "missing required field", http.StatusBadRequest)
21        return
22    }
23
24    if _, exists := notifications[req.ID]; exists {
25        http.Error(w, "notification already exists", http.StatusConflict)
26        return
27    }
28
29    notification := Notification{
30        ID:        req.ID,
31        Topic:     req.Topic,
32        Title:     req.Title,
33        CreatedAt: time.Now(),
34    }
35    notifications[notification.ID] = notification
36
37    w.Header().Set("Content-Type", "application/json")
38    w.WriteHeader(http.StatusCreated)
39    _ = json.NewEncoder(w).Encode(notification)
40}

這段程式可以跑，但它把太多責任放進 HTTP 邊界。只要要測「重複 ID 不可建立」，就必須走 HTTP；只要要改儲存方式，就必須改 handler。

【判讀】先拆 request DTO

request DTO 的核心責任是描述外部輸入格式。它可以有 JSON tag，但不應直接當成 domain model 或 repository model。

 1type createNotificationRequest struct {
 2    ID    string `json:"id"`
 3    Topic string `json:"topic"`
 4    Title string `json:"title"`
 5}
 6
 7func (r createNotificationRequest) validate() error {
 8    if strings.TrimSpace(r.ID) == "" {
 9        return ErrInvalidInput{Field: "id", Reason: "required"}
10    }
11    if strings.TrimSpace(r.Topic) == "" {
12        return ErrInvalidInput{Field: "topic", Reason: "required"}
13    }
14    return nil
15}

DTO 可以是 unexported，因為它只服務 HTTP handler。JSON tag 也停在 transport layer，不會污染 application command。

錯誤可以先用簡單型別表達：

1type ErrInvalidInput struct {
2    Field  string
3    Reason string
4}
5
6func (e ErrInvalidInput) Error() string {
7    return e.Field + ": " + e.Reason
8}

這個錯誤型別讓 handler 可以把輸入錯誤轉成 400 Bad Request，而不必靠字串比對。

【策略】command 表達 usecase 輸入

command 的核心責任是描述 application layer 要執行的行為。它不需要 JSON tag，也不需要知道 request body 來自 HTTP、WebSocket 或 CLI。

1type CreateNotificationCommand struct {
2    ID        string
3    Topic     string
4    Title     string
5    CreatedAt time.Time
6}

handler 負責 DTO -> command 的轉換：

1func (r createNotificationRequest) toCommand(now time.Time) CreateNotificationCommand {
2    return CreateNotificationCommand{
3        ID:        strings.TrimSpace(r.ID),
4        Topic:     strings.TrimSpace(r.Topic),
5        Title:     strings.TrimSpace(r.Title),
6        CreatedAt: now,
7    }
8}

CreatedAt 由 handler 或 usecase 決定都可以，但要一致。若時間是業務規則的一部分，通常由 usecase 注入 clock 會更穩；若只是 request 接收時間，handler 傳入也合理。重點是不要在測試中散落 time.Now()。

【執行】usecase 保存行為規則

usecase 的核心責任是處理行為規則與資料能力。重複檢查、儲存、事件發布或狀態轉移應該在 usecase，而不是 handler。

先定義 usecase 需要的 repository：

1type NotificationRepository interface {
2    Save(ctx context.Context, notification Notification) error
3    FindByID(ctx context.Context, id string) (Notification, bool, error)
4}

再定義 service：

1type CreateNotificationUsecase struct {
2    repository NotificationRepository
3}
4
5func NewCreateNotificationUsecase(repository NotificationRepository) *CreateNotificationUsecase {
6    return &CreateNotificationUsecase{repository: repository}
7}

執行 command：

 1func (u *CreateNotificationUsecase) Execute(ctx context.Context, cmd CreateNotificationCommand) (Notification, error) {
 2    if strings.TrimSpace(cmd.ID) == "" {
 3        return Notification{}, ErrInvalidInput{Field: "id", Reason: "required"}
 4    }
 5    if strings.TrimSpace(cmd.Topic) == "" {
 6        return Notification{}, ErrInvalidInput{Field: "topic", Reason: "required"}
 7    }
 8
 9    if _, exists, err := u.repository.FindByID(ctx, cmd.ID); err != nil {
10        return Notification{}, fmt.Errorf("find notification: %w", err)
11    } else if exists {
12        return Notification{}, ErrAlreadyExists{ID: cmd.ID}
13    }
14
15    notification := Notification{
16        ID:        cmd.ID,
17        Topic:     cmd.Topic,
18        Title:     cmd.Title,
19        CreatedAt: cmd.CreatedAt,
20    }
21
22    if err := u.repository.Save(ctx, notification); err != nil {
23        return Notification{}, fmt.Errorf("save notification: %w", err)
24    }
25
26    return notification, nil
27}

ErrAlreadyExists 可以是明確錯誤型別：

1type ErrAlreadyExists struct {
2    ID string
3}
4
5func (e ErrAlreadyExists) Error() string {
6    return "notification already exists: " + e.ID
7}

這樣 handler 可以用 errors.As 把它對應到 409 Conflict。

【執行】handler 只做轉換與 mapping

重構後 handler 的核心責任是 request -> command、result -> response、error -> HTTP status。它不直接碰 map，也不保存業務規則。

 1type NotificationCreator interface {
 2    Execute(ctx context.Context, cmd CreateNotificationCommand) (Notification, error)
 3}
 4
 5type NotificationHandler struct {
 6    creator NotificationCreator
 7    now     func() time.Time
 8}
 9
10func NewNotificationHandler(creator NotificationCreator, now func() time.Time) NotificationHandler {
11    return NotificationHandler{creator: creator, now: now}
12}

handler 實作：

 1func (h NotificationHandler) Create(w http.ResponseWriter, r *http.Request) {
 2    if r.Method != http.MethodPost {
 3        writeError(w, http.StatusMethodNotAllowed, "method_not_allowed", "method not allowed")
 4        return
 5    }
 6
 7    var req createNotificationRequest
 8    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 9        writeError(w, http.StatusBadRequest, "invalid_json", "request body must be valid JSON")
10        return
11    }
12
13    if err := req.validate(); err != nil {
14        writeError(w, http.StatusBadRequest, "invalid_input", err.Error())
15        return
16    }
17
18    notification, err := h.creator.Execute(r.Context(), req.toCommand(h.now()))
19    if err != nil {
20        writeUsecaseError(w, err)
21        return
22    }
23
24    writeJSON(w, http.StatusCreated, newNotificationResponse(notification))
25}

這個 handler 仍然有 HTTP 協定責任，但核心行為已經搬出去。未來 WebSocket action 或 worker 也可以建立 CreateNotificationCommand 呼叫同一個 usecase。

【策略】response struct 是對外 contract

response struct 的核心責任是描述 HTTP 回應格式。不要直接把 domain model 全部輸出，否則內部欄位會變成外部 API 承諾。

 1type notificationResponse struct {
 2    ID        string    `json:"id"`
 3    Topic     string    `json:"topic"`
 4    Title     string    `json:"title"`
 5    CreatedAt time.Time `json:"createdAt"`
 6}
 7
 8func newNotificationResponse(notification Notification) notificationResponse {
 9    return notificationResponse{
10        ID:        notification.ID,
11        Topic:     notification.Topic,
12        Title:     notification.Title,
13        CreatedAt: notification.CreatedAt,
14    }
15}

error response 也應該穩定：

 1type errorResponse struct {
 2    Code    string `json:"code"`
 3    Message string `json:"message"`
 4}
 5
 6func writeError(w http.ResponseWriter, status int, code string, message string) {
 7    writeJSON(w, status, errorResponse{
 8        Code:    code,
 9        Message: message,
10    })
11}

writeJSON 集中 JSON response 寫法：

1func writeJSON(w http.ResponseWriter, status int, value any) {
2    w.Header().Set("Content-Type", "application/json")
3    w.WriteHeader(status)
4    _ = json.NewEncoder(w).Encode(value)
5}

這個 helper 可以忽略 encode error，因為 response 已經開始寫出；正式服務通常會記錄 log。

【判讀】error mapping 是 handler 邊界

error mapping 的核心責任是把 application error 轉成 HTTP status 與對外 code。usecase 不應知道 HTTP status；handler 不應靠錯誤字串猜狀態。

 1func writeUsecaseError(w http.ResponseWriter, err error) {
 2    var invalid ErrInvalidInput
 3    if errors.As(err, &invalid) {
 4        writeError(w, http.StatusBadRequest, "invalid_input", invalid.Error())
 5        return
 6    }
 7
 8    var alreadyExists ErrAlreadyExists
 9    if errors.As(err, &alreadyExists) {
10        writeError(w, http.StatusConflict, "already_exists", "notification already exists")
11        return
12    }
13
14    writeError(w, http.StatusInternalServerError, "internal_error", "internal server error")
15}

內部錯誤不要直接回給 client。對外 message 應該穩定且安全；詳細錯誤留給 log 與 error chain。

【執行】usecase 測試不需要 HTTP

usecase 測試的核心目標是驗證行為規則。它應該直接建立 command，使用 fake repository，不需要 httptest。

 1type fakeNotificationRepository struct {
 2    existing map[string]Notification
 3    saved    []Notification
 4}
 5
 6func (f *fakeNotificationRepository) Save(ctx context.Context, notification Notification) error {
 7    f.saved = append(f.saved, notification)
 8    return nil
 9}
10
11func (f *fakeNotificationRepository) FindByID(ctx context.Context, id string) (Notification, bool, error) {
12    notification, ok := f.existing[id]
13    return notification, ok, nil
14}

測試建立成功：

 1func TestCreateNotificationUsecaseExecute(t *testing.T) {
 2    repo := &fakeNotificationRepository{existing: map[string]Notification{}}
 3    usecase := NewCreateNotificationUsecase(repo)
 4
 5    _, err := usecase.Execute(context.Background(), CreateNotificationCommand{
 6        ID:        "ntf_1",
 7        Topic:     "deployments",
 8        Title:     "Deploy finished",
 9        CreatedAt: time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
10    })
11    if err != nil {
12        t.Fatalf("execute usecase: %v", err)
13    }
14
15    if len(repo.saved) != 1 {
16        t.Fatalf("saved notifications = %d, want 1", len(repo.saved))
17    }
18}

這個測試速度快、錯誤定位明確。若失敗，問題在 usecase，不在 HTTP parsing。

【執行】handler test 專注 request/response

handler test 的核心目標是驗證 HTTP 協定行為。它應該使用 fake usecase，而不是真 repository。

 1type fakeNotificationCreator struct {
 2    got CreateNotificationCommand
 3    out Notification
 4    err error
 5}
 6
 7func (f *fakeNotificationCreator) Execute(ctx context.Context, cmd CreateNotificationCommand) (Notification, error) {
 8    f.got = cmd
 9    if f.err != nil {
10        return Notification{}, f.err
11    }
12    return f.out, nil
13}

測試成功 response：

 1func TestNotificationHandlerCreate(t *testing.T) {
 2    creator := &fakeNotificationCreator{
 3        out: Notification{
 4            ID:        "ntf_1",
 5            Topic:     "deployments",
 6            Title:     "Deploy finished",
 7            CreatedAt: time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
 8        },
 9    }
10    handler := NewNotificationHandler(creator, func() time.Time {
11        return time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
12    })
13
14    req := httptest.NewRequest(http.MethodPost, "/notifications", strings.NewReader(`{
15        "id": "ntf_1",
16        "topic": "deployments",
17        "title": "Deploy finished"
18    }`))
19    rec := httptest.NewRecorder()
20
21    handler.Create(rec, req)
22
23    if rec.Code != http.StatusCreated {
24        t.Fatalf("status = %d, want %d", rec.Code, http.StatusCreated)
25    }
26    if creator.got.Topic != "deployments" {
27        t.Fatalf("topic = %q, want deployments", creator.got.Topic)
28    }
29}

這個測試確認 handler 能解析 JSON、建立 command、呼叫 usecase、寫出狀態碼。它不測重複 ID 的儲存規則，那已經是 usecase 測試的責任。

【策略】integration test 只保留少數端到端路徑

integration test 的核心用途是確認組裝正確，不是覆蓋所有規則。當 usecase 與 handler 都已有單元測試，端到端測試只需要保留代表性成功與失敗路徑。

例如：

• POST /notifications 成功建立。
• invalid JSON 回 400。
• 重複 ID 回 409。

不要把所有欄位驗證都只放在 integration test。那會讓測試慢、失敗定位模糊，也讓重構成本升高。

重構步驟

從過重 handler 重構時，可以按這個順序：

1. 先補 handler 現有行為測試，鎖住 status code 與 response body。
2. 抽出 request DTO，但暫時不改行為。
3. 抽出 command 與 usecase，讓 handler 呼叫 usecase。
4. 把 repository 或 map 寫入移到 usecase 後方。
5. 抽出 response struct 與 error mapping helper。
6. 補 usecase 單元測試。
7. 縮減 handler 測試範圍，保留 request/response 行為。

每一步都應該讓程式可編譯、測試可跑。不要一次把 handler、repository、package 結構全部搬完。

設計檢查

檢查一：抽出真正的行為邊界

如果新函式仍然接收 http.ResponseWriter 和 *http.Request，那只是移動程式碼，還沒有分離 transport concern。

檢查二：domain model 和 response model 分開

JSON tag 是 transport contract。domain model 若直接承擔對外格式，未來內部欄位調整就會牽動 API 相容性。

檢查三：錯誤類型對應 HTTP 回應

輸入錯誤、重複資料、權限問題與內部錯誤應該對應不同 status code。錯誤型別與 error mapping helper 可以避免字串判斷。

檢查四：分層測試保護不同責任

端到端測試重要，但不應是唯一測試。usecase 規則越多，越需要直接測 command 與 fake repository。

本章不處理

本章先處理 HTTP handler 的轉換邊界；router、middleware 與 transaction，會在下列章節再往外延伸：

• Go 進階：逐步遷移到 ports/adapters 架構
• Go 進階：資料庫 transaction 與 schema migration

和 Go 教材的關係

這一章承接的是 request DTO、command 與 usecase 分層；如果你要先回看語言教材，可以讀：

• Go：用 interface 隔離外部依賴
• Go：如何新增一個即時訊息 action
• Go：如何新增 repository port
• Go：如何擴展狀態投影欄位

概念位置

Mock 遮蔽發生在 API 層和協議層之間的語意斷裂處。Mock 模擬的是最上層（方法簽名、參數型別、回傳值），真實行為發生在下面兩層（協議語意、執行環境）。遮蔽有兩種模式：功能存在但行為錯誤（mock 接受了真實服務不接受的輸入）、功能根本沒實作（mock 不需要該功能就能通過）。

可觀察訊號與例子

Mock 遮蔽的訊號是：test 全過但實機失敗的 bug 類型集中在外部互動（連線、認證、編碼）、修復後原有 test 不需要改動、bug 修復是型別轉換或編碼調整。FakeWebSocketChannel 的 sink.add(dynamic) 不區分 text/binary frame 是典型案例。

設計責任

面對 mock 遮蔽的正確策略是分層驗證 — mock 負責 API 層，protocol integration test 負責協議層。增加 mock test 數量無法跨越層級盲區。Mock 也不應該模擬協議行為 — 讓 mock 更「逼真」會讓 mock 本身變成需要維護和驗證的複雜元件。

三層語意與斷裂點

程式碼和外部服務之間的互動經過三層語意轉換，每一層描述不同粒度的行為。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 設計

觀察

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

代表性問題的案例

app_tunnel 的 ANSI parser 有 18 個 test，全部通過。測試資料是手寫的 SGR 色彩碼（\x1B[31mhello\x1B[0m），parser 正確解析這類序列。

真實 zsh 啟動後送出的控制序列包含 OSC 標題設定、CSI private mode、字元集指定等至少 5 種類型。Parser 只認識 SGR，其他全部透傳為亂碼（T.C3）。

18 個 test 覆蓋了 1 種序列類型。測試資料的代表性假設（「SGR 就是主要的序列類型」）和真實環境不符。

三種測試資料來源

手寫

開發者根據對輸入格式的理解手動建構測試字串。

優點：精確控制、容易理解、可以針對特定邊界條件設計。

缺點：受限於開發者對輸入分佈的認知。如果開發者不知道真實環境有哪些輸入類型，手寫的測試資料就是開發者認知的子集 — T.C3 就是這個模式。

適合場景：格式規格明確且有限（JSON schema、固定格式的設定檔）、邊界條件測試（空值、最大長度、特殊字元）。

錄製

從真實環境擷取實際的輸入資料，作為 test 的輸入。

優點：直接反映真實環境的輸入分佈，包含開發者不知道的輸入類型。

缺點：錄製的資料可能包含敏感資訊（需要脫敏）、資料量可能大（需要挑選代表性樣本）、真實環境的輸入可能隨時間改變（錄製的資料可能過時）。

適合場景：輸入格式複雜且規格不完整（終端機 escape 序列、網路封包、使用者產生的內容）、parser 類的功能（需要知道「真實輸入長什麼樣」）。

T.C3 如果用錄製的真實 zsh 啟動輸出作為測試資料，OSC 和 CSI private mode 會自然出現在輸入中。即使 parser 仍然不處理這些序列，test 至少能讓開發者看到「有 5 種序列類型，我只處理了 1 種」。

生成（Property-based testing）

用 generator 自動產生大量隨機或半隨機的輸入，驗證 parser 的行為是否符合通用性質（不崩潰、輸出長度 <= 輸入長度、冪等性）。

優點：覆蓋人類想不到的 edge case、發現意外的崩潰或無限迴圈。

缺點：不針對特定功能驗證（驗證的是通用性質，不是「OSC 序列是否被正確處理」）、generator 本身需要維護。

適合場景：parser、serializer、codec 等輸入格式複雜的功能。和手寫 test 互補 — 手寫驗證特定行為正確性，生成驗證通用穩定性。

兩類 test 的分工

T.C3 的策略建議是把 test 分成兩類：

功能正確性 test：用手寫乾淨字串驗證 parser 對已知序列的處理正確性。\x1B[31mhello\x1B[0m 應該產生紅色 token — 這是功能規格的驗證。

環境相容性 test：用錄製的真實輸出驗證 parser 在真實環境中的表現。不斷言「每個序列都被正確處理」，而是斷言「沒有崩潰」「沒有未處理序列殘留在可見輸出中」。

兩類 test 回答不同問題。功能正確性回答「parser 的邏輯對不對」，環境相容性回答「parser 在真實環境中夠不夠用」。

下一步路由

• Assertion 的品質判斷 → Assertion 品質三問
• Mock 邊界的判斷 → Mock 邊界判斷決策表
• Protocol integration test 用真實服務輸出 → testing 模組三 WebSocket 協議測試

要驗證什麼

從 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 → 成本判斷表

四類 log 點

每個功能的 log 點按執行時機分成四類。

啟動 log

功能開始執行時記錄。回答「這個功能是否被觸發了」。

啟動 log 包含觸發來源（使用者操作、系統排程、外部事件）和初始參數（連線目標、操作類型）。如果一個功能從未被觸發，啟動 log 的缺席就是線索。

步驟 log

功能執行過程中的每個關鍵步驟完成時記錄。回答「流程走到哪裡了」。

步驟 log 的粒度依功能複雜度而定。三步驟的功能每步記一條；十步驟的功能可以只記關鍵的三到五步。判斷標準是：如果這一步失敗，開發者是否需要知道失敗點在哪。

錯誤 log

步驟失敗、例外捕獲、非預期狀態出現時記錄。回答「出了什麼問題」。

錯誤 log 必須包含足夠的 context 讓開發者不需要重現問題就能判斷原因。至少包含：哪一步失敗、失敗原因（error message）、當時的關鍵狀態值。

完成 log

功能正常結束時記錄。回答「功能是否成功完成、花了多久」。

完成 log 包含執行結果和耗時。和啟動 log 配對使用 — 有啟動但沒有完成代表功能中途異常退出。

在功能規格中加可觀測性欄位

以 app_tunnel 的「連線到 ttyd 終端機」功能為例，傳統規格只寫：

• 輸入：使用者選擇的伺服器
• 處理：建立 WebSocket 連線、發送 auth token、開始接收 terminal output
• 輸出：終端機畫面顯示 terminal output

加上可觀測性欄位後：

這張表在功能規格階段就能寫出來，因為它只依賴功能的流程設計，不依賴實作細節。功能流程確定後，每一步在哪裡需要 log 點就確定了。

log 點命名規則

統一的命名規則讓 log 可以被 grep、過濾和統計。

階層式命名：{功能}.{步驟}.{事件}。例如 connect.ws.connected、connect.auth.failed。

事件後綴統一：start（啟動）、done（步驟完成）、failed（失敗）、complete（功能完成）。

和程式碼結構對應：log 點名稱對應到程式碼中的函式或模組。connect.biometric.done 對應 BiometricService.authenticate() 的成功路徑。這讓開發者看到 log 名稱就知道去哪裡找程式碼。

log 點規格的 review 檢查

功能規格 review 時，可觀測性欄位的檢查要點：

每步都有 log：流程中的每個步驟在成功和失敗時都有對應的 log 點。遺漏的步驟意味著該步驟出問題時無法從 log 判斷。

錯誤 log 有足夠 context：error log 只寫「連線失敗」不夠；需要寫「連線失敗」加上 error code、目標 URL、已完成的步驟。

敏感欄位有 redaction 標記：密碼、token、個人資料在 log 規格中標記為 redact，實作時用 redaction 機制處理。

啟動和完成配對：每個功能有啟動 log 就應該有完成 log，形成完整的生命週期。

下一步路由

• 三層 log 的詳細設計 → 三層 log 設計
• 事後補 log 和設計產物 log 的差異 → 「事後補 log」vs「設計產物 log」的品質差異
• Log 中的敏感資訊處理 → monitoring 模組七 資安

Back 按鈕 test

每個有 back 按鈕的畫面需要一個 test 驗證「按下 back 後導航到哪裡」。Back 按鈕的目標畫面依導航方式而定：

• context.push('/terminal') 進入 → back 回到推入前的畫面（首頁）
• context.go('/terminal') 進入 → back 行為依 router 設定，可能沒有上一頁

 1testWidgets('back from terminal returns to home (pushed)', (tester) async {
 2  await tester.pumpWidget(app());
 3  // 從首頁 push 到 terminal
 4  await tester.tap(find.text('Connect Terminal'));
 5  await tester.pumpAndSettle();
 6  expect(find.byType(TerminalScreen), findsOneWidget);
 7  // 按 back
 8  await tester.tap(find.byKey(Key('back_button')));
 9  await tester.pumpAndSettle();
10  expect(find.byType(HomeScreen), findsOneWidget);
11});

Route 可達性 test

Router 定義的每個路由都應該有從 UI 可達的路徑（ux-design 模組一 路由可達性）。Route 可達性 test 驗證「從首頁出發，透過 UI 操作能到達每個路由」。

 1testWidgets('enrollment route is reachable from home', (tester) async {
 2  await tester.pumpWidget(app());
 3  // 找到配對入口按鈕
 4  final enrollButton = find.text('Enroll Device');
 5  expect(enrollButton, findsOneWidget);
 6  // 點擊後到達 enrollment 畫面
 7  await tester.tap(enrollButton);
 8  await tester.pumpAndSettle();
 9  expect(find.byType(EnrollmentScreen), findsOneWidget);
10});

不可達的路由在 test 中表現為「找不到導航到該路由的 UI 元素」。如果 router 定義了 /enrollment 但首頁沒有對應按鈕，find.text('Enroll Device') 會找不到元素 — test 失敗暴露入口缺失。

go vs push 語意的 test

go 和 push 對返回堆疊的影響不同（ux-design 模組五 導航模式）。Test 需要驗證正確的導航方式被使用：

Push 語意：保留返回堆疊

Push 後按系統 back 鍵應該回到推入前的畫面。

 1testWidgets('push preserves back stack', (tester) async {
 2  await tester.pumpWidget(app());
 3  // push to enrollment
 4  await tester.tap(find.text('Enroll Device'));
 5  await tester.pumpAndSettle();
 6  // 系統 back 鍵
 7  final backButton = find.byTooltip('Back');
 8  await tester.tap(backButton);
 9  await tester.pumpAndSettle();
10  // 應該回到首頁
11  expect(find.byType(HomeScreen), findsOneWidget);
12});

Go 語意：替換路由堆疊

Go 後按系統 back 鍵的行為依 router 設定。如果 go 到的路由是根層級，系統 back 鍵可能退出 app 而非回到前一個畫面。

Test 策略：驗證 go 後的路由堆疊狀態。如果設計意圖是「切換工作區，不保留前一個畫面」，斷言系統 back 鍵不回到前一個畫面。

深層連結 test

深層連結（deep link）讓使用者從 app 外部直接進入特定畫面。Deep link test 驗證「直接導航到內部路由時，畫面和導航堆疊是否正確」。

1testWidgets('deep link to /terminal shows terminal', (tester) async {
2  await tester.pumpWidget(app(initialRoute: '/terminal'));
3  expect(find.byType(TerminalScreen), findsOneWidget);
4});

深層連結的特殊性在於使用者跳過了正常的導航流程。從首頁到 terminal 的正常流程可能經過認證 gate，但深層連結直接到 terminal — 認證 gate 是否仍然生效需要額外的 test。

下一步路由

• 狀態覆蓋策略 → Widget test 的狀態覆蓋策略
• Playwright 驗證流程 → Playwright 瀏覽器驗證流程
• 路由可達性的設計原則 → ux-design 模組一 路由可達性

對應 findings

待寫章節

• 三層 log 設計（連線生命週期 / protocol 訊息 / 使用者行為）
• 功能規格中的 log 點定義方法
• 自架 log endpoint vs 商業方案的取捨判斷
• 「事後補 log」vs「設計產物 log」的品質差異

跨分類引用

• → monitoring 模組二 Log Schema：本模組教「設計 log 點」，monitoring 教「log 收集到之後怎麼處理」
• → monitoring 模組七 資安：log 內容可能含 secret，SDK redaction 在這裡介入
• ← ux-design 模組一：狀態矩陣可加「可觀測性」欄位

測試是同一個 package 的行為說明

Go 測試的核心目標是驗證可觀察行為。測試用輸入、輸出與錯誤條件說明這段程式應該如何運作。

1func NormalizeName(input string) string {
2    input = strings.TrimSpace(input)
3    return strings.ToLower(input)
4}

這個函式的可觀察行為是：移除前後空白，並轉成小寫。測試應該檢查這個行為，而不是檢查函式內部是否真的先呼叫 TrimSpace 再呼叫 ToLower。

1func TestNormalizeName(t *testing.T) {
2    got := NormalizeName("  Alice  ")
3    want := "alice"
4
5    if got != want {
6        t.Fatalf("NormalizeName() = %q, want %q", got, want)
7    }
8}

這就是最小的 Go 單元測試：準備輸入，呼叫函式，比對結果，失敗時回報清楚訊息。

測試檔命名有固定規則

Go 測試檔的核心規則是檔名必須以 _test.go 結尾。測試函式必須以 Test 開頭，接收一個 *testing.T 參數，且沒有回傳值。

1// normalize_test.go
2func TestNormalizeName(t *testing.T) {
3    // ...
4}

go test 會自動找到這些檔案與函式。測試檔可以和被測程式放在同一個 package，也可以使用 package xxx_test 建立外部測試 package。

同 package 測試可以存取未匯出的函式與型別，外部測試只能使用匯出的 API。入門階段可以先用同 package 測試，等到需要從使用者視角驗證 public API 時，再使用外部測試。

失敗訊息要說明 got 與 want

測試失敗訊息的核心責任是幫助讀者快速定位差異。Go 社群常用 got 與 want 表示實際結果與預期結果。

1if got != want {
2    t.Fatalf("NormalizeName() = %q, want %q", got, want)
3}

這個訊息包含函式名稱、實際結果與預期結果。當測試失敗時，讀者不需要再打開測試檔猜哪個值錯了。

t.Fatal 與 t.Fatalf 會立刻中止目前測試；t.Error 與 t.Errorf 會記錄失敗但繼續執行。若後續檢查依賴目前結果，使用 Fatalf 比較安全。

1got, err := ParsePort("8080")
2if err != nil {
3    t.Fatalf("ParsePort() error = %v", err)
4}
5
6if got != 8080 {
7    t.Fatalf("ParsePort() = %d, want %d", got, 8080)
8}

如果解析已經失敗，後面再檢查數值沒有意義，所以先用 Fatalf 結束測試。

測試錯誤要明確檢查錯誤存在

錯誤情境測試的核心原則是同時檢查「是否有錯」與「錯誤是否符合預期」。只檢查回傳值常常不足以描述失敗行為。

 1func ParsePort(input string) (int, error) {
 2    port, err := strconv.Atoi(input)
 3    if err != nil {
 4        return 0, fmt.Errorf("parse port %q: %w", input, err)
 5    }
 6
 7    if port <= 0 {
 8        return 0, fmt.Errorf("port must be positive")
 9    }
10
11    return port, nil
12}

測試成功情境時，應確認沒有錯誤；測試失敗情境時，應確認錯誤確實發生。

1func TestParsePortInvalid(t *testing.T) {
2    _, err := ParsePort("abc")
3    if err == nil {
4        t.Fatalf("ParsePort() error = nil, want error")
5    }
6}

若程式使用 sentinel error 或可辨識的錯誤型別，可以再用 errors.Is 或 errors.As 檢查錯誤種類。不要只比對完整錯誤字串，除非錯誤訊息本身就是公開合約。

helper 函式可以降低重複

測試 helper 的核心用途是隱藏準備資料的細節，而不是隱藏真正的驗證邏輯。helper 應該讓測試主體更接近「這個行為應該成立」。

 1func mustParsePort(t *testing.T, input string) int {
 2    t.Helper()
 3
 4    port, err := ParsePort(input)
 5    if err != nil {
 6        t.Fatalf("ParsePort(%q) error = %v", input, err)
 7    }
 8
 9    return port
10}

t.Helper() 會讓失敗行號指向呼叫 helper 的測試，而不是 helper 內部。這能讓測試失敗時更快找到真正的案例位置。

helper 不應該把測試意圖藏起來。若 helper 名稱太抽象，或讀者必須跳進 helper 才知道測試在驗證什麼，這個 helper 可能反而降低可讀性。

測試要避免依賴不穩定環境

可靠測試的核心規則是讓輸入可控制、輸出可觀察。時間、隨機數、檔案系統、網路與全域狀態都可能讓測試不穩定。

1func IsExpired(now time.Time, deadline time.Time) bool {
2    return now.After(deadline)
3}

這個函式把 now 當成參數，因此測試可以傳入固定時間。

1func TestIsExpired(t *testing.T) {
2    now := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
3    deadline := time.Date(2026, 4, 22, 9, 0, 0, 0, time.UTC)
4
5    if !IsExpired(now, deadline) {
6        t.Fatalf("IsExpired() = false, want true")
7    }
8}

測試要在合適層級控制變因。單元測試優先控制依賴，整合測試才使用真實檔案、網路或服務。

下一章

下一章會介紹 table-driven 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 → 模組三：協議整合測試

三個判斷問題

斷言的是行為嗎

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

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

Playwright 和 widget test 的互補

Widget test 在 Flutter test framework 中執行，不需要瀏覽器，驗證的是 widget tree 的結構和狀態。Playwright 在真實瀏覽器中執行，驗證的是渲染後的 DOM 和視覺呈現。

兩者的分工：widget test 驗證「邏輯上正確」（該有的元素存在、該觸發的事件發生），Playwright 驗證「視覺上正確」（元素在正確的位置、顏色和大小符合設計）。

Playwright test 的基本結構

 1import { test, expect } from '@playwright/test';
 2
 3test('terminal screen shows connection status', async ({ page }) => {
 4  await page.goto('http://localhost:8080');
 5  
 6  // 點擊連線按鈕
 7  await page.click('text=Connect Terminal');
 8  
 9  // 等待畫面轉換
10  await page.waitForSelector('[data-testid="terminal-screen"]');
11  
12  // 驗證連線狀態顯示
13  const status = page.locator('[data-testid="connection-status"]');
14  await expect(status).toBeVisible();
15});

三個位置的斷言

Playwright test 中的斷言放在三個位置，各自驗證不同的東西：

假設斷言（test 開頭）：驗證 test 的前置條件。頁面載入成功、初始狀態正確。如果假設斷言失敗，test 的後續結果不可信。

行為斷言（操作之後）：驗證 UI 操作的即時效果。點擊按鈕後 dialog 出現、表單提交後顯示成功訊息。

互動斷言（流程結束）：驗證完整操作流程的最終狀態。多步驟操作完成後畫面回到預期狀態。

Selector 策略

Playwright 用 selector 定位 DOM 元素。Selector 的穩定性決定了 test 的維護成本。

推薦：data-testid

在 HTML 元素上加 data-testid 屬性，Playwright 用 [data-testid="xxx"] 定位。data-testid 不受 CSS class 改名、文字內容變更、DOM 結構調整影響。

1<button data-testid="connect-button">Connect Terminal</button>

可接受：文字內容

用 text=Connect Terminal 定位。在按鈕文字穩定的場景下可用，但多語系支援或文案調整時會斷。

避免：CSS selector

用 .btn-primary 或 #main-content > div:nth-child(2) 定位。CSS class 和 DOM 結構的改動頻率高，test 頻繁因無關變更而失敗。

和開發伺服器的整合

Playwright test 需要一個正在運行的 web 應用。整合方式：

手動啟動：開發者先啟動 dev server，再跑 Playwright test。適合本地開發。

自動啟動：Playwright 設定檔中指定 webServer 配置，Playwright 自動啟動 dev server，test 結束後自動停止。適合 CI。

1// playwright.config.ts
2export default defineConfig({
3  webServer: {
4    command: 'npm run dev',
5    port: 8080,
6    reuseExistingServer: !process.env.CI,
7  },
8});

下一步路由

• 視覺比對 → 螢幕截圖比對
• 狀態覆蓋策略 → Widget test 的狀態覆蓋策略
• 導航路徑 test → 導航路徑 test

觀察

app_tunnel 的 AnsiParser 負責解析終端機輸出的 ANSI escape 序列，轉換為帶色彩的文字 token。unit test 用手寫字串驗證：

1// 測試資料範例 — 乾淨的 SGR 色彩碼
2test('紅色文字', () {
3  final tokens = parser.parse('\x1B[31mhello\x1B[0m');
4  expect(tokens.first, isA<TextToken>());
5});

真實 zsh prompt 啟動後送出的控制序列（擷取自實機 log）：

1\x1B]0;user@host: ~\x07          ← OSC：設定終端機視窗標題
2\x1B[?2004h                      ← CSI private mode：啟用括號貼上模式
3\x1B[?1h                         ← CSI private mode：啟用應用程式游標鍵
4\x1B(B                           ← 字元集指定：選擇 ASCII
5\x1B[?25l                        ← CSI private mode：隱藏游標

Parser 只認識 \x1B[{數字;數字}{字母} 格式的標準 CSI，其他全部殘留在輸出中。

判讀

1. 測試資料的代表性是隱性假設。18 個 test 的斷言都正確 — \x1B[31m 確實應該產生紅色 token。但「測試輸入能代表真實輸入」是一個未經驗證的假設。真實 zsh 的輸出包含 5+ 種 escape 序列類型，測試只覆蓋了 1 種。

2. Parser 的行為對未知序列是「透傳」而非「報錯」。這是合理的設計 — 不認識的序列不應該讓 parser 崩潰。但透傳的後果是亂碼靜默出現在畫面上，不觸發任何錯誤或 log，開發者在 unit test 環境完全不會察覺。

3. 手寫測試資料 vs 錄製真實資料。如果測試資料是從真實 shell session 錄製的（capture 一次真實 zsh 啟動輸出），OSC 和 CSI private mode 會自然出現在測試輸入中，parser 的透傳行為會在 test 階段就被看到。

策略

1. 從真實環境錄製測試資料：用 script 命令或 WebSocket log 錄一次真實 shell session 的完整輸出，作為 integration test 的輸入。即使不改 parser 邏輯，至少能看到「哪些序列被透傳了」。
2. Parser 對未知序列記 warning log：透傳是合理的 fallback，但加一行 developer.log('Unknown escape: ${escape.codeUnits}') 讓開發者知道有未處理的序列。
3. 測試分兩類：「功能正確性」用手寫乾淨字串；「環境相容性」用錄製的真實輸出。兩類測試回答不同問題。

下一步路由

• 想理解測試資料代表性 → Test data 代表性
• 想建 protocol integration test 用真實 ttyd 輸出 → 模組三：協議整合測試
• 類似案例（mock 遮蔽） → T.C1 WS frame type mock 遮蔽

概念位置

名義 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 取代的依賴清單，讓後續讀者快速判斷驗證邊界。