模組五：測試與可靠性 on Tarragon

5.1 時間注入與狀態轉移測試

Wed, 22 Apr 2026 00:00:00 +0000

時間控制測試的核心原則是把「現在」變成可指定輸入。只要程式邏輯依賴目前時間、deadline、timeout、ticker 或過期判斷，測試就不應依賴真實等待。

本章目標

學完本章後，你將能夠：

用 now time.Time 測試純狀態轉移
用 func() time.Time 注入長生命週期元件的時間來源
用 table-driven test 覆蓋時間邊界
把 ticker 排程與單次工作拆開測
避免 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 邊界；如果你要先回看語言教材，可以讀：

小結

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

5.2 WebSocket integration test

Wed, 22 Apr 2026 00:00:00 +0000

WebSocket integration test 的核心目標是驗證 client 與 server 透過真實連線互動後，協定行為是否正確。它比單元測試慢，但能覆蓋 HTTP upgrade、read/write pump、router、server message、push flow 與 cleanup。

本章目標

學完本章後，你將能夠：

用 httptest.Server 建立真實 WebSocket 測試入口
將 http:// 測試 URL 轉成 ws://
用 deadline 避免 read/write 永久卡住
驗證 subscribe、push、error response 與 cleanup
分辨 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 只挑關鍵端到端流程。

建議分工：

測試類型	負責內容
unit test	router、payload validation、subscription state、TrySend
integration test	dial、upgrade、read/write pump、server response、cleanup
race test	hub、client state、repository 的並發存取

如果每個 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；如果你要先回看語言教材，可以讀：

小結

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

5.3 race condition 檢查

Wed, 22 Apr 2026 00:00:00 +0000

Race detector 的核心作用是找出測試執行期間發生的 data race。它能指出未同步讀寫同一份記憶體的位置，但不能取代 ownership、mutex、channel 與狀態邊界設計。

本章目標

學完本章後，你將能夠：

分辨 data race 與一般邏輯競爭
用 go test -race ./... 檢查並發路徑
寫出能觸發共享狀態讀寫的測試
依 race report 找到讀寫來源
選擇 mutex、channel owner 或 atomic 修正同步邊界

【觀察】並發 bug 常常不會穩定重現

Data race 的核心問題是測試可能偶爾通過、偶爾失敗，也可能完全不失敗但資料已經不安全。單次執行結果正確，不代表沒有未同步讀寫。

反模式：

1var count int
2
3func increment() {
4    count++
5}

count++ 不是原子操作。它包含讀取、加一、寫回。多個 goroutine 同時執行時，可能互相覆蓋結果，也可能被 race detector 偵測到未同步讀寫。

【判讀】data race 是未同步的並發讀寫

Data race 的核心定義是至少兩個 goroutine 同時存取同一份記憶體，其中至少一個是寫入，而且沒有同步保護。

觸發測試：

 1func TestIncrementRace(t *testing.T) {
 2    var wg sync.WaitGroup
 3
 4    for i := 0; i < 100; i++ {
 5        wg.Add(1)
 6        go func() {
 7            defer wg.Done()
 8            increment()
 9        }()
10    }
11
12    wg.Wait()
13}

一般 go test 不一定會失敗。go test -race 會在 runtime 偵測這類未同步讀寫，並輸出讀取與寫入發生的位置。

【執行】用 go test -race 跑到相關路徑

Race detector 的核心限制是只能檢查實際執行到的程式路徑。沒有被測試覆蓋的 goroutine、handler、repository 或 broadcast path，不會被它發現。

1go test -race ./...

這個指令會用 race detector 跑所有 package 的測試。它會比一般測試慢，但對含有 goroutine、共享 map、WebSocket hub、background worker 的服務非常重要。

若專案很大，可以先針對相關 package：

1go test -race ./internal/websocket ./internal/storage ./internal/worker

範圍縮小能讓日常執行更快，但合併前仍應跑完整路徑。

【策略】併發測試要讓共享狀態真的被同時讀寫

Race detector 的核心前提是測試要製造相關路徑。只建立 repository 卻不並發讀寫，race detector 沒有機會回報。

 1func TestRepositoryConcurrentAccess(t *testing.T) {
 2    repo := NewUserRepository()
 3    ctx := context.Background()
 4
 5    var wg sync.WaitGroup
 6    for i := 0; i < 100; i++ {
 7        i := i
 8        wg.Add(1)
 9        go func() {
10            defer wg.Done()
11            id := fmt.Sprintf("user_%d", i)
12            _ = repo.Save(ctx, User{ID: id})
13            _, _, _ = repo.Find(ctx, id)
14        }()
15    }
16
17    wg.Wait()
18}

這個測試的主要斷言在「讓 race detector 執行共享 map 的讀寫路徑」。若 repository 忘記加 lock，-race 會指出問題。

【執行】WebSocket hub 也需要 race path

WebSocket hub 的核心並發風險是 client 註冊、取消註冊、訂閱變更與 broadcast 可能同時發生。測試應讓這些路徑交錯執行。

 1func TestHubConcurrentBroadcastAndUnregister(t *testing.T) {
 2    hub := NewHub()
 3    clients := make([]*Client, 0, 100)
 4
 5    for i := 0; i < 100; i++ {
 6        client := NewTestClient(fmt.Sprintf("client_%d", i), 8)
 7        client.Subscribe("alerts")
 8        hub.clients[client] = struct{}{}
 9        clients = append(clients, client)
10    }
11
12    var wg sync.WaitGroup
13    wg.Add(2)
14
15    go func() {
16        defer wg.Done()
17        for i := 0; i < 100; i++ {
18            hub.Broadcast("alerts", ServerMessage{Type: "notification"})
19        }
20    }()
21
22    go func() {
23        defer wg.Done()
24        for _, client := range clients {
25            hub.unregisterClient(client)
26        }
27    }()
28
29    wg.Wait()
30}

這個測試是否需要 lock，取決於 hub 的設計。如果 hub 保證所有操作都在單一 event loop 中執行，測試就應該透過 channel 操作，而不是直接呼叫未同步方法。測試要符合 ownership 設計，不應製造不被 API 允許的並發。

【判讀】race report 要看讀寫兩端

Race report 的核心資訊是兩個位置：一端讀或寫，另一端寫。修正時不要只看最後一行，要找出是哪個共享資料缺少同步。

典型報告會包含：

1WARNING: DATA RACE
2Read at 0x...
3  example.com/app.(*UserRepository).Find()
4
5Previous write at 0x...
6  example.com/app.(*UserRepository).Save()

這表示 Find 和 Save 同時碰到同一份資料，且缺少同步。修正方向是在 repository owner 補上 mutex、channel ownership 或其他同步邊界。

【策略】修正方式要對應狀態形狀

修正 data race 的核心選擇是建立正確同步邊界。常見方法有 mutex、channel owner、atomic。

方法	適用情境	注意事項
mutex	多方法讀寫同一份 map/slice/state	lock 要保護完整不變式
channel owner	狀態修改可集中成事件 loop	要設計 reply、shutdown、backpressure
atomic	單一數值 counter 或 flag	不適合複雜狀態

Mutex 範例：

 1type Counter struct {
 2    mu    sync.Mutex
 3    value int
 4}
 5
 6func (c *Counter) Inc() {
 7    c.mu.Lock()
 8    defer c.mu.Unlock()
 9    c.value++
10}
11
12func (c *Counter) Value() int {
13    c.mu.Lock()
14    defer c.mu.Unlock()
15    return c.value
16}

鎖應該屬於擁有狀態的型別，並保護一個清楚的不變條件。只為了讓 race detector 安靜而到處加鎖，會讓 ownership 分散，後續仍然難以判斷資料一致性。

【判讀】race-free 不代表行為正確

Race detector 的核心邊界是它只找 data race，不保證並發邏輯正確。沒有 data race 的程式仍可能 deadlock、漏訊息、順序錯誤、重複 close 或違反資料語意。

例如：

1select {
2case client.send <- message:
3default:
4    // drop
5}

這段程式可能沒有 data race，但「queue full 時丟訊息」是否正確是服務語意問題。Race detector 不會告訴你該丟、該斷線、還是該寫可靠 queue。

因此並發測試要分成兩層：

用 go test -race 找未同步記憶體存取。
用行為測試檢查 channel close、queue full、context cancel、cleanup、timeout。

【測試】把 race check 納入固定流程

Race check 的核心價值來自重複執行。只在出事後手動跑，效果有限。

建議流程：

1go test ./...
2go test -race ./...

日常開發可以先跑相關 package，提交前或 CI 跑完整 race suite。若 race suite 太慢，至少讓含有 hub、repository、worker、client state 的 package 固定跑 -race。

本章不處理

本章先處理共享 state、channel ownership 與 goroutine lifecycle 的 race 風險；lock-free 與完整 memory model，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是共享狀態、channel ownership 與 lifecycle；如果你要先回看語言教材，可以讀：

小結

go test -race 是 Go 並發服務的基本安全網，但它只檢查測試執行到的 data race。你仍然需要設計清楚的 state owner、lock boundary、channel ownership 與行為測試。Race-free 不是正確性的全部；它只是可靠性的第一層檢查。

5.4 table-driven test 的設計邊界

Wed, 22 Apr 2026 00:00:00 +0000

Table-driven test 的核心邊界是每張表只描述一個行為維度。它能降低重複並清楚列出案例，但不適合把多種 setup、多種執行方式與多種斷言硬塞進同一個測試。

本章目標

學完本章後，你將能夠：

判斷什麼行為適合 table-driven test
設計欄位少、意圖清楚的測試表
發現 table test 膨脹成迷你框架的訊號
拆分 validation、repository error、integration flow
寫出能定位失敗情境的子測試名稱

【觀察】table-driven test 很容易被濫用

Table-driven test 的核心風險是「減少重複」被誤解成「所有案例都塞進一張表」。當表格開始同時控制 HTTP method、request body、repository 狀態、WebSocket client、expected log、expected event，測試就會變成難懂的迷你框架。

失控表格示意：

 1tests := []struct {
 2    name          string
 3    method        string
 4    body          string
 5    setupRepo     bool
 6    setupClient   bool
 7    queueFull     bool
 8    wantStatus    int
 9    wantMessage   string
10    wantEvent     bool
11    wantLog       bool
12}{
13    // many unrelated cases
14}

這種表格看似統一，實際上混合了 HTTP validation、repository error、client queue full、event emission、log assertion。讀者必須同時理解多個系統層，才能看懂單一案例。

【判讀】好表格描述同一個行為維度

好的 table-driven test 的核心特徵是所有案例共享相同 setup、相同執行方式、相同斷言方式。表格只改變資料，不改變測試流程。

 1func TestNormalizeTopic(t *testing.T) {
 2    tests := []struct {
 3        name  string
 4        input string
 5        want  string
 6    }{
 7        {name: "trim spaces", input: " alerts ", want: "alerts"},
 8        {name: "lowercase", input: "ALERTS", want: "alerts"},
 9        {name: "empty", input: "", want: ""},
10    }
11
12    for _, tt := range tests {
13        t.Run(tt.name, func(t *testing.T) {
14            got := NormalizeTopic(tt.input)
15            if got != tt.want {
16                t.Fatalf("NormalizeTopic(%q) = %q, want %q", tt.input, got, tt.want)
17            }
18        })
19    }
20}

這張表只測 topic normalization。每個案例都只有 input 和 want，失敗時也能立刻看出是哪個 normalization 規則壞了。

【策略】表格欄位越多，越要懷疑測試邊界

Table 欄位的核心警訊是大量欄位只被少數案例使用。這通常表示不同測試目的被合併在一起。

拆分判斷：

現象	問題	建議
很多 `setupX bool`	setup 不一致	拆成不同測試
很多 `wantX bool`	斷言目標不一致	拆成不同測試
loop 內大量 `if tt...`	測試流程不一致	拆表或改成具名測試
案例名稱很長仍說不清	行為維度太多	回到單一行為
helper 隱藏主要斷言	可讀性下降	讓斷言留在測試本文

表格不是越通用越好。測試的第一責任是讓失敗可定位，不是消除所有重複。

【執行】validation 適合 table test

Validation 的核心特徵是輸入和輸出形狀一致，因此很適合 table-driven test。

 1func TestValidateSubscribeRequest(t *testing.T) {
 2    tests := []struct {
 3        name    string
 4        request SubscribeTopicRequest
 5        wantErr bool
 6    }{
 7        {
 8            name:    "valid topic",
 9            request: SubscribeTopicRequest{Topic: "alerts"},
10            wantErr: false,
11        },
12        {
13            name:    "empty topic",
14            request: SubscribeTopicRequest{Topic: ""},
15            wantErr: true,
16        },
17        {
18            name:    "blank topic",
19            request: SubscribeTopicRequest{Topic: "   "},
20            wantErr: true,
21        },
22    }
23
24    for _, tt := range tests {
25        t.Run(tt.name, func(t *testing.T) {
26            err := ValidateSubscribeRequest(tt.request)
27            if (err != nil) != tt.wantErr {
28                t.Fatalf("error = %v, wantErr %v", err, tt.wantErr)
29            }
30        })
31    }
32}

這張表只問一件事：request 是否有效。它不測 WebSocket connection、不測 hub、不測 repository，因此案例可以保持簡潔。

【執行】狀態轉移也適合 table test

狀態轉移的核心特徵是輸入狀態、事件、期待輸出狀態。只要流程一致，就適合 table-driven test。

 1func TestJobTransition(t *testing.T) {
 2    tests := []struct {
 3        name    string
 4        current JobStatus
 5        event   EventType
 6        want    JobStatus
 7        wantErr bool
 8    }{
 9        {
10            name:    "pending starts",
11            current: JobPending,
12            event:   EventJobStarted,
13            want:    JobRunning,
14        },
15        {
16            name:    "running finishes",
17            current: JobRunning,
18            event:   EventJobFinished,
19            want:    JobSucceeded,
20        },
21        {
22            name:    "finished cannot start again",
23            current: JobSucceeded,
24            event:   EventJobStarted,
25            wantErr: true,
26        },
27    }
28
29    for _, tt := range tests {
30        t.Run(tt.name, func(t *testing.T) {
31            got, err := Transition(tt.current, tt.event)
32            if (err != nil) != tt.wantErr {
33                t.Fatalf("error = %v, wantErr %v", err, tt.wantErr)
34            }
35            if err == nil && got != tt.want {
36                t.Fatalf("status = %s, want %s", got, tt.want)
37            }
38        })
39    }
40}

這張表的欄位都服務同一個行為：job status transition。若未來要測 repository 寫入失敗，應另開測試，不要塞進這張表。

【判讀】不同 setup 應拆成不同測試

測試拆分的核心原則是 setup 不同，通常就不是同一張表。HTTP validation、repository error、client queue full 都需要不同環境。

較清楚的拆法：

 1func TestSubscribeValidation(t *testing.T) {
 2    // 只測 request validation
 3}
 4
 5func TestSubscribeAddsTopic(t *testing.T) {
 6    // 只測成功訂閱後 client state
 7}
 8
 9func TestSubscribeReturnsErrorWhenClientQueueFull(t *testing.T) {
10    // 只測 send buffer 滿載時的錯誤語意
11}

這些測試可能有少量重複，但每個測試的失敗原因更清楚。測試重複一點可以接受；測試意圖混在一起會讓維護成本更高。

【策略】helper 只包樣板，不包判斷

Test helper 的核心責任是降低重複 setup，不應隱藏主要斷言。讀者應能在測試本文看到這個測試到底在驗證什麼。

可以包的樣板：

1func mustJSON(t *testing.T, value any) json.RawMessage {
2    t.Helper()
3    data, err := json.Marshal(value)
4    if err != nil {
5        t.Fatalf("marshal json: %v", err)
6    }
7    return data
8}

不建議包成這樣：

1func assertSubscribeScenario(t *testing.T, tt subscribeScenario) {
2    // setup HTTP, setup WebSocket, setup repository,
3    // execute action, check response, check logs, check events
4}

後者把測試主要邏輯藏進 helper。表格看起來短，但讀者必須跳到 helper 才知道每個欄位如何影響流程。

【執行】子測試名稱要描述情境

子測試名稱的核心作用是讓失敗輸出可定位。名稱應描述情境，不應只寫編號或重複函式名稱。

1tests := []struct {
2    name string
3    // ...
4}{
5    {name: "missing topic"},
6    {name: "unknown action"},
7    {name: "queue full returns unavailable"},
8}

go test 輸出會包含 TestValidateSubscribeRequest/missing_topic 這類資訊。當 CI 失敗時，讀者能先知道哪個情境壞了，再看 got/want 差異。

命名應該描述輸入情境或規則，不需要寫成完整句子，也不要只寫 case 1。

【測試】table test 本身也要保持可讀

Table-driven test 的核心完成標準是讀者能掃過表格就理解規則。若必須讀整個 loop 才懂欄位意義，表格設計就不夠清楚。

自檢問題：

這張表是否只測一個行為？
每個欄位是否幾乎每個案例都用得到？
測試 loop 裡是否有大量條件分支？
子測試名稱是否能定位失敗情境？
got/want 斷言是否直接留在測試本文？

任一題答否，先考慮拆測試，而不是加更多欄位。

本章不處理

本章先處理單一行為的多組資料案例；property-based、fuzz 與 snapshot 測試，會在下列章節再往外延伸：

Go 進階：CI、fuzz、load test 與 chaos testing

和 Go 教材的關係

這一章承接的是 test case 設計、handler boundary 與 command 驗證；如果你要先回看語言教材，可以讀：

小結

Table-driven test 適合同一個行為的多組資料，不適合混合多種 setup 與斷言。欄位膨脹、loop 裡大量 if tt...、helper 隱藏主要判斷，都是拆表訊號。好的測試表讓案例更清楚，而不是把測試變成迷你框架。