概念位置

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

三層語意與斷裂點

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

CLI 輸入的特殊性

桌面終端機的鍵盤直接傳送按鍵事件，沒有中間的輸入法處理層。使用者按 l 就是 l，按 Tab 就是 Tab，按 Ctrl+C 就是 interrupt signal。

手機鍵盤在使用者和 app 之間插入了 IME 層。使用者按 l 時，IME 可能等待後續按鍵組合成完整詞彙再傳送；使用者按的按鍵可能被自動校正替換；使用者的輸入被記錄到 IME 詞庫供跨 app 學習。

Terminal app 需要繞過或控制 IME 層的這些行為。app_tunnel 的 TextField 用 TextInputType.visiblePassword + autocorrect: false + enableSuggestions: false + enableIMEPersonalizedLearning: false 四個參數關閉 IME 的自動行為（U.C3）。

整行送出 vs 逐字元：protocol 層的影響

整行送出和逐字元送出在 UI 層看起來只是「按 Enter 送出整行」和「每個按鍵即時送出」的差別，但在 protocol 層是兩種不同的通訊模式。

整行送出

Client 端累積使用者輸入，使用者按 Enter 時傳送完整指令字串加換行符（ls -la\n）。Server 端收到完整行後處理。

Protocol 設計簡單：每個 WebSocket frame 是一個完整指令。Server 不需要管理部分輸入的狀態，也不需要即時回應 Tab 或方向鍵。

代價：使用者無法在手機上使用 Tab 補全（Tab 被 IME 攔截或不存在）、無法用方向鍵在指令中移動游標（移動的是 TextField 的游標，不是 server 端的 readline 游標）。

逐字元送出

Client 端每個按鍵即時傳送一個 WebSocket frame。Server 端的 shell 即時處理每個字元，包括 Tab 補全（server 回傳補全結果）、Ctrl+C（server 中斷當前程序）、方向鍵（server 端 readline 移動游標）。

Protocol 設計複雜：每個按鍵一個 frame，frame 內容是單一字元或控制序列。Server 端必須維護 readline 狀態。Client 端必須正確編碼控制字元（Ctrl+C = 0x03, Tab = 0x09）。

代價：protocol 複雜度高，每個按鍵都有網路延遲。在高延遲網路上輸入體驗差（打字後要等 round-trip 才看到回顯）。

決策在 protocol 層做

app_tunnel 選擇整行送出，犧牲 Tab 補全換取簡單的 protocol 設計。這個決策應該在 protocol spec 階段做 — 因為它影響 server 端（ttyd）的行為預期和 client 端的 frame 格式。在 UI 實作時才臨時決定，可能和 server 端的行為預期不一致。

特殊按鍵的 UI 方案

手機沒有 Esc、Tab、Ctrl、方向鍵。Terminal app 需要額外的 UI 元件提供這些按鍵。

底部工具列

固定在鍵盤上方的一排按鈕，提供常用特殊鍵。app_tunnel 的工具列包含 Esc、Tab、Ctrl、四個方向鍵。

工具列的設計考量：按鈕大小（手指能精確觸碰的最小尺寸約 44x44 pt）、排列順序（最常用的放中間）、長按行為（長按 Ctrl 是否支援 Ctrl 組合鍵）。

Ctrl 組合鍵

Ctrl+C（中斷）、Ctrl+D（EOF）、Ctrl+Z（暫停）在 CLI 操作中頻繁使用。手機上的實作方式通常是：按下 Ctrl 按鈕後進入「Ctrl 模式」，下一個按鍵自動加 Ctrl 前綴。

下一步路由

• 四維度決策表 → 輸入機制決策表
• 安全敏感輸入框的 IME 控制 → IME 安全 checklist
• 表單場景的輸入設計 → 表單 UX 模式

要驗證什麼

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

對應 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 的斷言

服務啟動成本

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