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

要驗證什麼

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

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

三種服務管理方案

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 管理處理啟動和停止真實服務的工程問題。