在 Go 原始碼裡開啟 net/http 這個目錄,列出來是這樣的:
$ ls -p $(go env GOROOT)/src/net/http | head -20alpn_test.goasync_test.gocgi/client.goclient_test.goclientconn.goclientconn_test.goclientserver_test.goclone.gocookie.gocookie_test.gocookiejar/csrf.gocsrf_test.godoc.goexample_filesystem_test.goexample_handle_test.goexample_test.goexport_test.gofcgi/這只是前 20 行。整個目錄有 77 個 .go 檔案,38 個以 _test.go 結尾,和程式碼按字母順序交錯排在一起。中間還夾著一個名字很奇怪的 export_test.go,往下翻還有一個叫 testdata/ 的目錄。
第一眼的感覺是亂。寫過 Java 的人習慣 src/main 和 src/test 兩棵樹分開,Python 專案也常有一個 tests/ 目錄。Go 為什麼非要把測試和程式碼擺在一起?能不能挪出去?Kubernetes 這種幾千個測試檔案的專案,難道也這麼擺?要起資料庫的整合測試、要起整個叢集的端到端測試,又放在哪裡?
本文從這個目錄出發,先看 Go 自己為什麼這樣設計,再到 15 個大型 Go 專案裡看它們實際怎麼做。
一、測試檔案在構建中的位置
現象:測試程式碼看起來混進了產品程式碼
先做一個小專案,後面所有實驗都用它。shortlink 是一個短連結服務,三個包:
slug:把自增 ID 編成短字串。匯出Encode和Valid,內部有一個未匯出的校驗函式checksum;store:儲存連結,import了slug;cmd/server:程式入口。
給 slug 寫兩個測試檔案:slug_test.go 宣告 package slug,測 checksum;example_test.go 宣告 package slug_test,寫一個示例 ExampleEncode。現在 slug/ 目錄裡有三個檔案,和 net/http 一樣,程式碼和測試混在一起。
問題是:測試程式碼會不會被編進產品?
分析:go build 看不見 _test.go
go list 可以看到 go 工具怎麼給這個目錄的檔案分類:
$ go list -f 'GoFiles={{.GoFiles}} TestGoFiles={{.TestGoFiles}} XTestGoFiles={{.XTestGoFiles}}' ./slugGoFiles=[slug.go] TestGoFiles=[slug_test.go] XTestGoFiles=[example_test.go]同一個目錄被分成了三組。go build 只用第一組;go test 才會把後兩組加進來1。驗證一下:加測試檔案之前和之後各編一次 cmd/server,兩個二進位制的 sha256 完全相同,都是 eeb392905a59…。
再用 go tool nm 看符號。go test -c 產出的 slug.test 裡有 Encode、Valid、checksum、TestChecksumStable、TestRoundTrip,還有一個 slug_test.ExampleEncode;產品二進位制 server 裡只有 Encode 和 checksum,連 Valid 都因為沒被用到被裁掉了。
測試二進位制具體是怎麼拼出來的,go list -test -deps 列得很清楚:
$ go list -test -deps ./slug | grep shortlinkexample.com/shortlink/slugexample.com/shortlink/slug [example.com/shortlink/slug.test]example.com/shortlink/store [example.com/shortlink/slug.test]example.com/shortlink/slug_test [example.com/shortlink/slug.test]example.com/shortlink/slug.test(這裡的 store 是因為後面第三節的實驗讓測試 import 了它,先留意它也出現在了列表裡。)
圖 1 把這件事畫了出來。go test ./slug 做的事情是:把 slug.go 和 slug_test.go 編成一個“帶測試的 slug”,再把依賴它的包(這裡是 store)針對這個版本重新編譯一份,把 example_test.go 編成另一個包 slug_test,最後生成一個 main 把所有 Test、Example 函式串起來。每個包各得到一個這樣的測試二進位制1。
所以“混在一起”只發生在目錄列表裡,產物是分開的。既然只是看著亂,為什麼不乾脆把測試挪到單獨的目錄?
二、包與目錄的關係
第一次嘗試:把測試挪進 tests/
照 Java 的習慣,在專案根目錄建一個 tests/,把 slug_test.go 搬進去。包名只能改成 tests,引用 checksum 時寫成 slug.checksum:
$ go test ./...# example.com/shortlink/tests [example.com/shortlink/tests.test]tests/slug_test.go:10:17: undefined: slug.checksum? example.com/shortlink/slug [no test files]FAIL example.com/shortlink/tests [build failed]未匯出的函式看不見了。那隻測匯出的 Encode 和 Valid 呢?能編譯,也能透過,但覆蓋率變成了這樣:
$ go test -cover ./... example.com/shortlink/slug coverage: 0.0% of statementsok example.com/shortlink/tests 0.014s coverage: [no statements]
$ go test -cover -coverpkg=./slug ./tests/ok example.com/shortlink/tests 0.006s coverage: 93.3% of statements in ./slugslug 顯示 0%,tests 顯示“沒有語句”,要手動加 -coverpkg 才能看到真實的 93.3%。而測試放在原處時,go test -cover ./slug 直接就是 93.3%。另一個小麻煩是,改完 slug 在它的目錄裡跑 go test .,得到的是 [no test files]。
原因:Go 的包就是一個目錄
為什麼 Java 可以分開,Go 不行?關鍵在“包”是什麼。
Java 的 package net.twwy.slug 是一個名稱空間,src/main 和 src/test 兩個目錄裡宣告同一個包名的類就屬於同一個包,包級私有的方法互相可見。Go 沒有這一層:一個目錄就是一個包,可見性以包為界,首字母小寫的識別符號只在這個目錄裡可見。測試想看到 checksum,就必須和它在同一個目錄、宣告同一個包名。
Rust 的選擇很接近:單元測試寫在原始檔裡的 #[cfg(test)] mod tests 中,只有跨模組的整合測試才放到 tests/ 目錄。兩種語言都是“能看內部的測試貼著程式碼,只看公開介面的測試才可以離開”。
所以在 Go 裡,單元測試貼著包放不是風格偏好,而是語言的可見性規則決定的。下一節的統計會看到,15 個大型專案沒有一個把單元測試搬出去。
至於“看著亂”,可以交給編輯器。VS Code 的檔案巢狀功能在設定里加一條 "*.go": "${capture}_test.go",slug_test.go 就會摺疊到 slug.go 下面2;GoLand 在 Project 工具視窗的設定選單裡開啟 File Nesting,加一條父字尾 .go、子字尾 _test.go 的規則,效果一樣3。
單元測試的位置定下來了。不過前面 example_test.go 宣告的是 package slug_test,和 slug_test.go 不是同一個包。同一個目錄裡,為什麼允許兩種測試包名?
三、同目錄下的兩種測試包
內部測試與外部測試
Go 允許測試檔案宣告兩種包名1:
package slug:內部測試,和程式碼是同一個包,能訪問未匯出的東西,適合測細節,比如checksum;package slug_test:外部測試,被編譯成另一個包,只能像普通呼叫方一樣import "example.com/shortlink/slug",只看得到匯出的 API。示例函式通常寫在這裡,因為文件裡展示的就是呼叫方寫的程式碼。
外部測試看起來只是“自願少看一點”,它真正解決的是另一個問題。
現象:測試裡 import 一個依賴自己的包
store 用 slug 生成短串。現在想在 slug 的測試裡確認:store 生成的 100 個短串都能透過 Valid。寫成內部測試:
$ go test ./slug/package example.com/shortlink/slug imports example.com/shortlink/store from store_int_test.go imports example.com/shortlink/slug from store.go: import cycle not allowed in testFAIL example.com/shortlink/slug [setup failed]測試檔案屬於 slug 包,slug 又 import 了 store,而 store import 了 slug,形成了環。只把第一行改成 package slug_test(呼叫改成 slug.Valid),就透過了:
=== RUN TestKeysFromStoreAreValid--- PASS: TestKeysFromStoreAreValid (0.00s)ok example.com/shortlink/slug 0.005s圖 3 左邊是環的來歷。右邊的 slug_test 是另一個包,它和 store 一樣都是 slug 的使用者,依賴關係是一棵樹。第一節 go list -test -deps 裡那行 store [slug.test] 就是這樣來的:store 被針對帶測試的 slug 重新編譯了一份,再交給 slug_test 使用。
標準庫裡這種情況很常見:net/http 的測試要用 net/http/httptest 起測試伺服器,而 httptest 本身 import 了 net/http,所以凡是要用 httptest 的 net/http 測試,都只能寫成 package http_test。
export_test.go:給外部測試開一扇小門
外部測試偶爾也想看一眼內部。net/http 的做法是 export_test.go,它的開頭註釋寫得很直白:“Bridge package to expose http internals to tests in the http_test package.”4 檔案宣告 package http(內部),內容是一串賦值,把未匯出的東西換個匯出的名字:
var ( DefaultUserAgent = defaultUserAgent NewLoggingConn = newLoggingConn ExportServerNewConn = (*Server).newConn ...)在 slug 上照做:export_test.go 裡寫 var Checksum = checksum。外部測試裡調 slug.Checksum("3") 透過了;而在 cmd/server 裡調同一個名字:
$ go build ./cmd/servercmd/server/main.go:12:46: undefined: slug.Checksum因為檔名以 _test.go 結尾,這扇門只在測試構建裡存在,產品程式碼和別的包永遠看不到它。Go 倉庫裡有 79 個這樣的檔案。
兩種測試包各佔多少,不同專案差別很大。Go 倉庫自己 46.8% 的測試檔案是外部測試,CockroachDB 是 32.6%,Hugo 是 34.2%,Kubernetes 只有 4.4%,MinIO 不到 1%。net/http 正好一半一半:19 個 package http,19 個 package http_test。
單元測試的去處到這裡就清楚了:貼著包,按需要選內部或外部包名。可是整合測試要起資料庫,端到端測試要起整個叢集,它們也貼著包放嗎?
四、整合測試的位置與門控
15 個倉庫的統計
先看實際情況。下面統計了 15 個大型 Go 倉庫(排除 vendor、third_party、testdata)。“在獨立測試目錄”指路徑裡有一段叫 test、tests、integration、e2e*、integrationtest*、acceptance、roachtest 之類名字的測試檔案,是個近似口徑。
| 倉庫 | _test.go | 在獨立測試目錄 | 外部測試包 | 整合 / e2e 測試去處 |
|---|---|---|---|---|
| golang/go | 1905 | 3.2% | 46.8% | test/ 下 3473 個編譯器測試程式;cmd/go 的 951 個指令碼 |
| Kubernetes | 3572 | 24.7% | 4.4% | test/integration、test/e2e 等 |
| etcd | 419 | 44.9% | 16.0% | tests/,獨立的 Go 模組 |
| Prometheus | 290 | 0% | 4.8% | 都在包裡,-short 跳過慢的 |
| CockroachDB | 3179 | 4.4% | 32.6% | 包內起程序內叢集;roachtest 上真叢集 |
| moby | 844 | 30.0% | 4.6% | integration/(舊的 integration-cli/ 已廢棄) |
| Terraform | 694 | 5.0% | 1.7% | 包內,TF_ACC 環境變數開啟 |
| TiDB | 2032 | 16.0% | 29.5% | tests/ 與包內 test 子目錄 |
| containerd | 356 | 22.2% | 2.0% | integration/ |
| Grafana | 2478 | 13.4% | 6.1% | 包內,TestIntegration 字首;pkg/tests |
| Consul | 905 | 3.6% | 4.0% | 包內,-short 跳過 |
| Istio | 767 | 23.5% | 11.6% | tests/integration,integ 構建標籤 |
| Hugo | 395 | 0% | 34.2% | 包內,txtar 指令碼 |
| Gitea | 1070 | 23.6% | 10.4% | tests/integration、tests/e2e |
| MinIO | 247 | 0% | 0.8% | 包內 |
Go 倉庫那 3.2% 主要是 cmd/compile/internal/test 這個名叫 test 的包;它真正的“獨立測試目錄”是根目錄的 test/,裡面不是 _test.go,沒計入。
這張表說明兩件事。第一,沒有一個專案把單元測試搬出去,搬出去的只有整合測試和端到端測試。moby 的測試規範寫得最明白:單元測試“located in the package they test”,API 整合測試放在 ./integration/<component>5。第二,即使是整合測試,也有一半的專案留在包裡(Prometheus、Consul、Terraform、MinIO 一個都沒搬)。
所以整合測試真正要回答的不是“放哪個目錄”,而是:怎麼讓 go test ./... 預設不跑它? 整合測試慢,要外部依賴,開發時每儲存一次就跑一遍是受不了的。
門控的六種方式
各專案用的辦法可以歸成六種:
| 方式 | 代表 | 裸跑 go test ./... 時 | 代價 |
|---|---|---|---|
| 按目錄,在指令碼里排除 | Kubernetes、moby、Gitea | 會跑,靠 make test 排除 | 規則在 Makefile 裡;k8s 的 test.sh 用正則去掉 test/integration 等路徑 |
| 構建標籤 | Istio 的 integ,etcd 的 e2e、integration | 不編譯 | 改程式碼時,帶標籤的檔案不參與編譯檢查 |
testing.Short() | Consul(258 個檔案)、Prometheus | 會跑,加 -short 才跳過 | 預設是全跑,日常要記得加 -short |
名字字首 + -run | Grafana 的 1492 個 TestIntegration* | 會跑,配合 -short 跳過 | 靠約定;Grafana 用輔助函式檢查名字字首 |
| 環境變數 | Terraform 的 TF_ACC | 跳過 | 跳過是靜默的,CI 忘了設就等於沒測 |
| 獨立模組 | etcd 的 tests/ | 不進入 | 每個模組要分別跑,需要 replace |
表中的 -short 是 go test 自帶的開關,測試裡用 testing.Short() 判斷後呼叫 t.Skip6。Kubernetes 的 make test 用一組正則把 test/e2e、test/e2e_node、test/integration 等路徑排除在外,整合測試由 make test-integration 單獨跑,而且預設帶 -short=true7。Grafana 的組合值得多看一眼:SkipIntegrationTestInShortMode(t) 先檢查測試名是不是以 TestIntegration 開頭,不是就直接 t.Fatal,然後 -short 時跳過。Makefile 裡單元測試帶 -short,整合測試用 -run "^TestIntegration"8。名字約定於是被程式碼強制執行了。Terraform 的驗收測試會在雲上建立真實資源,所以預設必須跳過,程式碼裡寫著“TF_ACC must be set to run acceptance tests, as they provision real resources”9。
Istio 是構建標籤的典型使用者,tests/integration 下 146 個檔案都以 //go:build integ 開頭10。表裡唯一標成紅色的是構建標籤,它看起來最乾淨,問題出在哪?
構建標籤的盲區
做個實驗。給 store 寫一個帶 //go:build integration 的整合測試,裡面呼叫 s.Get(k)。然後有人在生產程式碼裡把 Get 改名成 Lookup,只改了生產程式碼:
$ go build ./... && go vet ./... && go test ./...? example.com/shortlink/cmd/server [no test files]ok example.com/shortlink/slug 0.005s? example.com/shortlink/store [no test files]exit=0
$ go vet -tags integration ./...vet: store/store_integration_test.go:14:16: s.Get undefined (type *store.Store has no field or method Get)exit=1編譯、vet、測試三道檢查全部透過,store 甚至顯示 [no test files]。壞掉的整合測試要等到有人帶上標籤才會被發現。編輯器也一樣:gopls 預設不帶標籤,開啟這個檔案時找不到它所屬的包,跳轉和補全都失效。
把同一個測試改成用 testing.Short() 門控:
func TestPutGetIntegration(t *testing.T) { if testing.Short() { t.Skip("集成测试,-short 时跳过") } ...}同樣的改名,go test -short ./... 立刻報 s.Get undefined,store [build failed]。修好以後,-short 下它只是一行 --- SKIP。測試程式碼每次都被編譯,只是不被執行。
用構建標籤的專案也意識到了這個問題。etcd 的 tests/common 裡有一個 unit_test.go,標籤是 //go:build !(e2e || integration),專門在不帶標籤時提供一份預設實現,註釋寫著:沒配標籤時“IDE may complain “Unresolved reference ‘WithAuth’””,所以要定義一個預設的11。
在 etcd 的 tests/ 裡還藏著第六種方式:它是一個獨立的 Go 模組。為了測試單獨建一個模組,圖的是什麼?
五、測試依賴與獨立模組
現象:只在測試裡用的庫,進了別人的依賴圖
繼續用 shortlink 做實驗。slug 的一個測試用了 testify 的 require,go mod tidy 以後 go.mod 裡多了 require github.com/stretchr/testify v1.11.1。這很正常,測試依賴也要記錄。
接著建一個下游專案 app,它 import 了 shortlink/slug,自己也用 testify,但想固定在舊版本 v1.8.0:
$ go get github.com/stretchr/testify@v1.8.0go: removed example.com/shortlink v0.0.0go: downgraded github.com/stretchr/testify v1.11.1 => v1.8.0
$ go mod tidy && go list -m github.com/stretchr/testifygithub.com/stretchr/testify v1.11.1go get 發現 shortlink 要求 testify 至少 v1.11.1,降級就只能把 shortlink 整個移除;tidy 把 shortlink 加回來以後,testify 又回到了 v1.11.1。app 用到的只是 slug.Encode,shortlink 的測試一行都不會進 app 的二進位制,但測試的依賴實實在在地參與了 app 的版本選擇。
原因:依賴圖按模組算,不按包算
Go 的最小版本選擇(MVS)以模組為單位:每個依賴模組 go.mod 裡的直接 require 都進入依賴圖12。go.mod 不區分“這條依賴是給測試用的”,所以測試依賴和產品依賴一樣,會向下遊傳遞版本下限。
etcd 是一個倉庫裡放了十幾個模組的專案,client/v3、api、server 都會被別人 import。它的 robustness 測試要用 porcupine 做線性一致性檢查,還接了 antithesis 的故障注入 SDK。這些依賴都只寫在 tests/go.mod 裡,server/go.mod、client/v3/go.mod、api/go.mod 裡一個都沒有13。tests/go.mod 用 replace 指向同倉庫的 ../server、../client/v3 等目錄,測試的永遠是同一次提交的程式碼。
單獨成模組還有一個副作用:./... 不會進入含 go.mod 的子目錄14,所以在 etcd 根目錄 go test ./... 根本碰不到 tests/,這本身就是一道門。代價是每個模組要分別跑,etcd 的 scripts/test.sh 裡 unit_pass 用 run_for_all_workspace_modules 帶 -short 遍歷所有模組,整合和 e2e 再各自進 tests/ 跑15。
這個辦法在小專案裡不必要,testify 這樣的小庫進 go.mod 無傷大雅。它針對的是“會被很多人 import 的庫,測試卻要拖一堆重型依賴”的情況。
整合測試的問題解決了。etcd 的 tests/ 裡除了整合測試,還有 e2e 和 robustness。整合測試和端到端測試到底差在哪?
六、端到端測試與被測物件的距離
同一份測試,兩種跑法
etcd 的 tests/common 給了一個很好的對照:同一個 TestKVPut,按構建標籤選不同的“叢集實現”11。
實測(三個子用例:無 TLS、手動 TLS、自動 TLS):
$ go test -c -tags integration ./common && ./common.test -test.run 'TestKVPut$' -test.v--- PASS: TestKVPut (0.72s) --- PASS: TestKVPut/NoTLS (0.21s) --- PASS: TestKVPut/PeerTLS_and_ClientTLS (0.20s) --- PASS: TestKVPut/PeerAutoTLS_and_ClientAutoTLS (0.30s)
$ go test -c -tags e2e ./common && ./common.test -test.run 'TestKVPut$' -test.vINFO spawning process {"args": ["/.../etcd/bin/etcd", "--name=TestKVPutNoTLS-test-0", ...--- PASS: TestKVPut (5.51s) --- PASS: TestKVPut/NoTLS (0.80s) --- PASS: TestKVPut/PeerTLS_and_ClientTLS (0.99s) --- PASS: TestKVPut/PeerAutoTLS_and_ClientAutoTLS (3.71s)斷言一模一樣,差別只在叢集在哪。整合模式下,etcd 的服務端程式碼和測試編進同一個二進位制(38 MB),競態檢測、覆蓋率、斷點都能直接用;e2e 模式下測試二進位制只是一個客戶端,真正的服務端是事先 make build 編好的 bin/etcd(這一步花了 1 分 21 秒),測的是使用者實際拿到的那個程式:命令列引數解析、程序啟動、證書檔案讀取都走一遍,慢了 7 倍多。etcd 的指令碼里也寫著:e2e 跑的是預先編好的二進位制,--race、-cover 這些引數對它不起作用15。
所以整合測試和 e2e 測試的區別,可以理解成被測物件離測試程序有多遠。
從程序內到真實叢集
圖 8 按這個距離排了四級,每級舉了真實專案的例子。
第一、二級通常叫整合測試。 Kubernetes 的 138 個整合測試目錄裡,有 107 個的 main_test.go 只有一行 framework.EtcdMain(m.Run)。它先 exec.LookPath("etcd") 找到本機的 etcd 起一個真程序,再在測試程序裡啟動 apiserver 和控制器,測完用 goleak 檢查有沒有遺留的 goroutine16。etcd 不好塞進測試程序(它是另一個專案),apiserver 是自己的程式碼,放進來才方便除錯,這就是它停在第二級的原因。
第三級開始是 e2e。 Prometheus 有一個很巧的辦法:cmd/prometheus/main_test.go 的 TestMain 檢查命令列,看到 -test.main 就直接呼叫 main();測試用 exec.Command(os.Args[0], "-test.main", "--config.file=...") 把測試二進位制自己當成 Prometheus 服務端拉起來17。這樣不需要事先編譯,被測程式和測試永遠是同一份程式碼,而且這些測試在 -short 時跳過。
第四級的測試本身是一個獨立程式。 Kubernetes 的 test/e2e 下有 513 個普通 .go 檔案,只有 33 個 _test.go。測試用例寫在普通包裡,再由 e2e_test.go 用一長串空匯入拼起來18:
import ( _ "k8s.io/kubernetes/test/e2e/apimachinery" _ "k8s.io/kubernetes/test/e2e/apps" _ "k8s.io/kubernetes/test/e2e/network" _ "k8s.io/kubernetes/test/e2e/storage" ...)go test -c 編出一個 e2e.test,帶到任何能訪問叢集的機器上,用 ginkgo 的標籤選擇要跑的用例。CockroachDB 的 roachtest 也一樣,pkg/cmd/roachtest/tests 下 237 個檔案都是普通 .go,編成 roachtest 程式,在雲上開真實叢集跑 nightly19。
為什麼 e2e 用例要寫在普通 .go 裡?試一下就知道:在 slug/helper_test.go 裡定義一個 MustEncode,再在 store 的測試裡呼叫它:
$ go test ./storestore/store_test.go:10:36: undefined: slug.MustEncode_test.go 裡的東西只屬於那個包的測試二進位制,別的包永遠 import 不到。幾百個 e2e 用例要按領域分包、再拼進一個二進位制,就只能寫成普通包。這條規則在下面講測試替身時還會出現。
測試離被測物件越遠,輸入和期望輸出也越大:一份配置檔案、一段 SQL、一整個站點。這些測試資料放在哪?
七、測試資料:testdata、golden 檔案與資料驅動
testdata 目錄
開頭 net/http 裡那個 testdata/ 是 go 工具的約定:名叫 testdata 的目錄被完全忽略1,./... 也不會進入它14。在 slug/testdata/broken.go 裡寫一行根本不是 Go 的東西,go build ./... && go vet ./... 照樣透過。所以 testdata 裡可以放任何東西,包括故意寫錯的 Go 檔案(Go 倉庫的編譯器測試就大量這麼用)。
go test 執行測試時,工作目錄就是包的目錄,所以測試裡直接寫 os.ReadFile("testdata/xxx") 就能讀到。資料和讀它的測試在同一個目錄,一起移動、一起刪除。
golden 檔案:把期望輸出存成檔案
輸出很長時,把期望值寫在測試程式碼裡很難維護。常見做法是 golden 檔案:期望輸出存在 testdata/*.golden 裡,加一個 -update 開關,開關開啟時用實際輸出重寫檔案。給 slug 寫一個:
var update = flag.Bool("update", false, "用当前输出重写 testdata 里的 golden 文件")
func TestEncodeGolden(t *testing.T) { var b strings.Builder for _, id := range []uint64{0, 1, 30, 31, 961, 1 << 40} { fmt.Fprintf(&b, "%d\t%s\n", id, Encode(id)) } golden := filepath.Join("testdata", "encode.golden") if *update { os.WriteFile(golden, []byte(b.String()), 0o644) } want, _ := os.ReadFile(golden) if got := b.String(); got != string(want) { t.Errorf("输出和 %s 不一致\n--- got\n%s--- want\n%s", golden, got, want) }}第一次執行因為檔案不存在而失敗,go test ./slug -update 生成它,之後 golden 檔案和程式碼一起提交,評審時能直接看到輸出變了什麼。
它能抓到什麼普通測試抓不到的東西?做個實驗:把 checksum 裡的乘數從 7 改成 11,相當於有人“最佳化”了校驗演算法。
| 測試 | 結果 | 為什麼 |
|---|---|---|
TestRoundTrip | PASS | 編碼和校驗用的是同一個新演算法,仍然自洽 |
TestChecksumStable | PASS | 只測了單字元 "3",乘數不起作用 |
TestEncodeGolden | FAIL | 31 → 23b 變成 23f;961 → 223w 變成 223c |
ExampleEncode | FAIL | want 53z,got 53h |
兩個“自洽”的測試都透過了,但已經發出去的短連結全部失效。只有把舊輸出存下來的測試發現了這件事。
Kubernetes 把這個思路用在了 API 上。staging/src/k8s.io/api/testdata/HEAD/ 裡有 579 個序列化好的 API 物件(json、yaml、protobuf 三種格式),每次釋出 1.x.0 之後,把 HEAD 複製一份成 v1.34.0、v1.35.0 這樣的目錄。測試保證當前程式碼還能把每個舊版本的資料解碼成相同的物件20。
資料驅動:測試用例本身就是檔案
再往前一步,連“調什麼函式、輸入是什麼”也寫進檔案,Go 程式碼只負責讀檔案、執行、比對。Russ Cox 在 GopherCon Australia 2023 的演講裡專門講過這種寫法:把測試用例寫成文字檔案,比寫成 Go 的表格更容易增加21。
Prometheus 的 PromQL 測試是一個完整的例子。promql/promqltest/testdata/ 下 22 個 .test 檔案,是一門小小的測試語言22:
load 5m http_requests{job="api-server", instance="0", group="production"} 0+10x10 http_requests{job="api-server", instance="1", group="production"} 0+20x10 ...
# Simple sum.eval instant at 50m SUM BY (group) (http_requests{job="api-server"}) {group="canary"} 700 {group="production"} 300load 灌入時間序列,eval 執行一條查詢並列出期望結果。Go 那邊只有一行:
func TestEvaluations(t *testing.T) { promqltest.RunBuiltinTests(t, newTestEngine(t))}實測 go test ./promql -run TestEvaluations 用 6.44 秒跑了 2434 個子測試。把第 17 行的 700 改成 701,失敗資訊是 expected 701 for {group="canary"} but got 700,子測試名裡帶著 aggregators.test/line_16,可以直接回到檔案裡改。加一個 PromQL 函式的測試,只需要在 .test 檔案里加幾行,不用寫 Go。
CockroachDB 是這種寫法用得最多的專案。它的 datadriven 庫規定了一種通用格式:命令和輸入在上面,---- 下面是期望輸出,--rewrite 用實際輸出改寫檔案23。pkg/ 下的 testdata 裡有 5990 個檔案,其中 4693 個是這種格式。SQL 邏輯測試更進一步:pkg/sql/logictest/testdata/logic_test/ 下 610 個 SQL 檔案,由生成器按 26 種叢集配置(單節點、三節點多租戶、五節點等)生成 generated_test.go,一共 5764 個測試函式24。同一個 SQL 檔案在 26 種拓撲上各跑一遍,這在手寫的 Go 測試裡很難做到。
各專案的測試資料格式彙總如下:
| 專案 | 檔案 | 規模 | 更新期望輸出 |
|---|---|---|---|
| Go 編譯器 | test/*.go,首行 // run、// errorcheck 等指令 | 3473 個 | 手寫;go test cmd/internal/testdir 驅動 |
| go 命令 | cmd/go/testdata/script/*.txt(txtar 指令碼) | 951 個 | 手寫 |
| Prometheus | promqltest/testdata/*.test | 22 個 / 2433 條 | 手寫 |
| CockroachDB | datadriven 檔案 | 4693 個 | --rewrite |
| logictest SQL 檔案 | 610 個 → 5764 個測試 | ||
| Kubernetes | api/testdata/HEAD 與各版本快照 | 579 個 / 版本 | 每次發版複製 HEAD |
| TiDB | tests/integrationtest 的 t/*.test 與 r/*.result | 264 個 | run-tests.sh -r |
| Hugo | testscripts/*.txt;hugolib 裡內聯的 txtar 站點 | 80 個 + 418 處 | 手寫 |
| Gitea | models/fixtures/*.yml,一張表一個檔案 | 78 張表 | 手寫,測試前灌進資料庫 |
txtar 是 Go 自己的一種純文字歸檔格式:用 “-- 檔名 --” 分隔多個檔案,一段測試指令碼連同它要用的所有檔案寫在一個 .txt 裡。
Go 倉庫自己是這種寫法最早的使用者:根目錄 test/ 下的編譯器測試程式靠首行指令宣告“應該能執行”還是“應該在第幾行報什麼錯”25,go 命令的 951 個指令碼測試把命令、期望輸出和所需檔案一起寫進 txtar26。Hugo 用的是從 cmd/go 抽出來的 testscript 庫27,Gitea 的 fixtures 則是最樸素的一種:一張表一個 YAML 檔案,測試開始前灌進資料庫28。
這些檔案大多放在被測包的 testdata/ 裡,因為它們就是這個包的測試的輸入,跟著包走最自然。例外是 Go 編譯器的 test/、Hugo 的 testscripts/、TiDB 的 tests/integrationtest 和 Gitea 的 models/fixtures:它們測的是整個程式或整個資料庫,不屬於某一個包,於是和整合測試一樣離開了包。
測試資料解決了輸入和期望輸出。可被測程式碼往往還依賴資料庫、外部 API、另一個服務,這些依賴在測試裡拿什麼代替?
八、依賴替身:真實例項、fake 與 mock
各專案用什麼替身
Go 社群常說“不要用 mock 框架,寫個 fake 就好”。實際統計一下各專案的測試檔案:
| 倉庫 | type Fake… | gomock | testify/mock | testcontainers |
|---|---|---|---|---|
| golang/go | 28 | 0 | 0 | 0 |
| Kubernetes | 808 | 0 | 20 | 0 |
| etcd | 35 | 0 | 0 | 0 |
| Prometheus | 27 | 0 | 2 | 0 |
| CockroachDB | 78 | 37 | 31 | 0 |
| TiDB | 37 | 85 | 18 | 0 |
| Grafana | 448 | 25 | 362 | 1 |
| Consul | 36 | 0 | 180 | 19 |
| moby、containerd、Hugo、Gitea、MinIO | 0–31 | 都是 0 | ||
gomock、testify/mock 按 import 它們的 .go 檔案數統計;type Fake… 按型別宣告數統計。
把各專案的做法放在一起,能看出一個大致的優先順序。
能起真的,就起真的。 第六節那四級距離裡,第一級其實就是“替身”的最佳形態:net/http/httptest 起一個真的 HTTP 伺服器,etcd 的整合模式起一個真的 etcd 叢集,CockroachDB 的 testcluster 起真的資料庫節點,只是都在測試程序裡。Kubernetes 整合測試用的也是真 etcd。TiDB 用 unistore(mockstore)在程序內模擬 TiKV,名字叫 mock,實際是一個能存能取的完整儲存引擎。容器化的依賴(testcontainers)反倒很少見,15 個倉庫裡只有 Consul 用得多一點。
起不了的,寫 fake。 fake 是一個能工作的簡化實現。Kubernetes 的 808 個 Fake 型別裡最典型的是 client-go 的假 clientset:由 client-gen 從 API 定義生成,內部用一個記憶體裡的物件儲存響應增刪改查,183 個測試檔案直接 fake.NewSimpleClientset(...) 或 fake.NewClientset(...)29。moby 的測試規範直接建議:“Consider accepting unexported interfaces instead of structs so that fakes can be provided for dependencies.”5
mock 框架是第三選擇。 gomock、testify/mock 生成的物件記錄“期望哪個方法被以什麼引數呼叫幾次”。它適合依賴非常多、又只關心呼叫協議的場景,Grafana 的服務層就是這樣。代價是測試和實現的呼叫順序綁在一起,重構時測試會大面積失敗。
TiDB 還有一個少見的辦法:failpoint。原始碼裡寫 failpoint.Inject("name", func() {...}) 這樣的標記,平時是空操作;make ut 先執行 failpoint-enable,把這些標記改寫成可以從測試裡觸發的程式碼,跑完再還原30。它用來在真實程式碼路徑上注入故障,606 個檔案用了它。
共享的測試工具必須是普通包
替身寫好了,往往很多包都要用。第六節的實驗已經說明:_test.go 裡的東西別的包 import 不到。所以所有被共享的測試工具都是普通 .go 檔案組成的包:Go 標準庫的 net/http/httptest、internal/testenv,Kubernetes 的 client-go/kubernetes/fake,CockroachDB 的 pkg/testutils 下幾十個子包。它們會出現在模組裡,但只要產品程式碼不 import,就不會進產品二進位制,第一節的實驗已經驗證過連結器的行為。
共享工具一多,第三節的 import cycle 又回來了。CockroachDB 幾乎每個包的測試都要起一個測試伺服器,可伺服器的實現 pkg/server import 了幾乎所有包。它的解法是讓工具包只持有一個“工廠”變數:
test_server_shim.go 的註釋說得很清楚:這些介面讓測試“set up test servers without importing the server package (avoiding circular dependencies)”31。CockroachDB 的 311 個 TestMain 裡有 284 個做的就是這件事,再加上 randutil.SeedForTests() 固定隨機種子。這是第三節外部測試包思路的放大版:真正“看得見一切”的程式碼只出現在測試二進位制的最外層。
九、回到開頭:一個專案可以怎麼擺
回到開頭的 net/http。現在再看那個目錄:_test.go 和程式碼交錯,是因為 Go 的包就是目錄,單元測試必須在裡面;export_test.go 是給外部測試包開的門;testdata/ 是 go 工具約定的資料目錄。它看起來亂,但每個檔案的位置都由規則決定,不需要額外的約定。
把各專案的做法合在一起,一箇中等規模的 Go 專案可以這樣擺:
幾條取捨的理由,都來自前面的實驗:
- 整合測試優先用
testing.Short()門控,它保證測試程式碼每次都被編譯;用構建標籤的話,要像 etcd 那樣給不帶標籤的情況提供一份樁,並在 CI 裡專門帶標籤跑一次go vet。 - 外部測試包按需用:寫示例、測試需要 import 使用者時用
_test包,測內部細節時用同名包。 - 需要共享的測試工具放普通包(
internal/testutil這樣的位置,外部無法 import),不要指望別的包能用到你_test.go裡的函式。 - 輸出複雜、需要防止相容性破壞的地方,用 golden 檔案加
-update;被測物件是一門語言或一個命令時,考慮把用例寫成檔案。 - e2e 測試的重型依賴開始影響下游時,再把它拆成獨立模組。
小結
_test.go和程式碼放在一起,會不會混進產品? 不會。go build只看GoFiles,加不加測試檔案,產品二進位制的 sha256 都一樣;go test為每個包臨時拼一個測試二進位制。- 為什麼不能像 Java 一樣挪進 tests/ 目錄? 因為 Go 的包就是目錄,挪出去就是另一個包,看不到未匯出的識別符號,覆蓋率也算錯。“看著亂”可以用編輯器的檔案巢狀解決。
- 同一個目錄裡為什麼有兩種測試包?
package slug_test是另一個包,能同時 import 被測包和它的使用者而不成環;export_test.go只在測試構建裡把內部借給它。 - 整合測試放哪? 15 個專案的單元測試全部貼著包,離開包的只有整合和 e2e。關鍵是門控:目錄、構建標籤、
-short、名字字首、環境變數、獨立模組各有代價,構建標籤會讓壞掉的測試程式碼透過所有預設檢查。 - 測試依賴為什麼要單獨一個模組?
go.mod不區分測試依賴,它們照樣約束下游的版本選擇;etcd 把 porcupine 等重型依賴關進tests/go.mod。 - e2e 和整合測試差在哪? 被測物件離測試程序的距離。etcd 同一個測試,程序內 0.72 秒,拉起真二進位制 5.51 秒;Kubernetes 的 e2e 用例寫在 513 個普通
.go裡,因為_test.go不能被別的包 import。 - 測試資料放哪? 各包的
testdata/。golden 檔案能發現“自洽”測試發現不了的相容性破壞;Prometheus、CockroachDB 把用例本身寫成檔案,Go 程式碼只是直譯器。 - 依賴用什麼替? 能起真的就起真的,其次是 fake,mock 框架排最後;共享的替身必須是普通包,迴圈依賴用 TestMain 注入工廠解決。
參考資料
參考資料
-
go help test:Test packagespkg.go.dev ↗go test 重新編譯每個包並加上 *_test.go;包名帶 _test 字尾的測試檔案編譯成單獨的包;go 工具忽略名為 testdata 的目錄。https://pkg.go.dev/cmd/go#hdr-Test_packages ↩ ↩2 ↩3 ↩4
-
Explorer file nestingcode.visualstudio.com ↗explorer.fileNesting.patterns 裡寫 "*.go": "${capture}_test.go"。https://code.visualstudio.com/docs/getstarted/userinterface#_explorer-file-nesting ↩
-
File Nesting dialogjetbrains.com ↗Project 工具視窗的設定選單裡開啟,規則是“父字尾 + 子字尾”,可以自己加 .go → _test.go。https://www.jetbrains.com/help/go/file-nesting-dialog.html ↩
-
golang/go:src/net/http/export_test.gogithub.com ↗“Bridge package to expose http internals to tests in the http_test package.”https://github.com/golang/go/blob/0d37007fda071631fbcb520b99c85a8e4c93108a/src/net/http/export_test.go ↩
-
moby:TESTING.mdgithub.com ↗單元測試 located in the package they test;API 整合測試在 ./integration/
;integration-cli 已廢棄。 https://github.com/moby/moby/blob/b711d21792db6db488de976eb3c4a653c92c3bc3/TESTING.md ↩ ↩2 -
Package testingpkg.go.dev ↗testing.Short、TestMain、Example 函式的 Output 註釋、子測試。https://pkg.go.dev/testing ↩
-
kubernetes:hack/make-rules/test.shgithub.com ↗make test 用正則按路徑排除 test/e2e、test/e2e_node、test/integration 等目錄。https://github.com/kubernetes/kubernetes/blob/765dd1d145814464051056c0eff14b7357eace82/hack/make-rules/test.sh ↩
-
grafana:Makefile(test-go-unit / test-go-integration)github.com ↗單元測試帶 -short;整合測試用 -run "^TestIntegration",SkipIntegrationTestInShortMode 要求測試名以 TestIntegration 開頭。https://github.com/grafana/grafana/blob/cdd0e0a52b51ebfb78603dc4e4cfb36f07b0a39c/Makefile ↩
-
terraform:internal/backend/remote-state/gcs/backend_test.gogithub.com ↗“TF_ACC must be set to run acceptance tests, as they provision real resources”。https://github.com/hashicorp/terraform/blob/55988303ba5651e41e2c9097e208468c8eb3da4b/internal/backend/remote-state/gcs/backend_test.go ↩
-
istio:tests/integrationgithub.com ↗146 個檔案以 //go:build integ 開頭。https://github.com/istio/istio/tree/64b84bc308d5533e26f71ab7241e2c3eb927d67e/tests/integration ↩
-
etcd:tests/commongithub.com ↗同一份測試,按構建標籤選 IntegrationTestRunner 或 E2eTestRunner;unit_test.go 是不帶標籤時的樁。https://github.com/etcd-io/etcd/tree/f3221acd10232a9f6ef0c36438517bdbc918ea26/tests/common ↩ ↩2
-
Go Modules Reference:Module graph pruninggo.dev ↗go 1.17 以後的模組,依賴圖裡保留每個依賴模組 go.mod 的直接 require,測試用的依賴也在其中。https://go.dev/ref/mod#graph-pruning ↩
-
etcd:tests/go.modgithub.com ↗獨立模組 go.etcd.io/etcd/tests/v3,用 replace 指向同倉庫的 server、client 等模組。https://github.com/etcd-io/etcd/blob/f3221acd10232a9f6ef0c36438517bdbc918ea26/tests/go.mod ↩
-
go help packages:Package lists and patternspkg.go.dev ↗./... 不包括 vendor、testdata、以 _ 或 . 開頭的目錄,以及含 go.mod 的子目錄。https://pkg.go.dev/cmd/go#hdr-Package_lists_and_patterns ↩ ↩2
-
etcd:scripts/test.shgithub.com ↗unit_pass 帶 -short 跑所有模組;integration_pass、e2e_pass、robustness_pass 各跑 tests/ 下對應目錄。https://github.com/etcd-io/etcd/blob/f3221acd10232a9f6ef0c36438517bdbc918ea26/scripts/test.sh ↩ ↩2
-
kubernetes:test/integration/framework/etcd.gogithub.com ↗EtcdMain:exec.LookPath("etcd") 起一個真實 etcd 程序,並用 goleak 檢查洩漏的 goroutine。https://github.com/kubernetes/kubernetes/blob/765dd1d145814464051056c0eff14b7357eace82/test/integration/framework/etcd.go ↩
-
prometheus:cmd/prometheus/main_test.gogithub.com ↗TestMain 看到 -test.main 引數就調 main(),測試用 exec.Command(os.Args[0], "-test.main", ...) 把自己當服務端拉起來。https://github.com/prometheus/prometheus/blob/a2fda0ef4638518a6a6fb27fc48be88fbd732f4b/cmd/prometheus/main_test.go ↩
-
kubernetes:test/e2e/e2e_test.gogithub.com ↗一長串空匯入把 apps、network、storage 等普通包拼進一個 e2e.test 二進位制。https://github.com/kubernetes/kubernetes/blob/765dd1d145814464051056c0eff14b7357eace82/test/e2e/e2e_test.go ↩
-
cockroach:pkg/cmd/roachtestgithub.com ↗tests/ 下 237 個檔案,普通 .go,編成 roachtest 程式在真實雲叢集上跑。https://github.com/cockroachdb/cockroach/tree/d30c905fff79ef825adc96bcc647f1872a90f2ff/pkg/cmd/roachtest ↩
-
kubernetes:staging/src/k8s.io/api/testdatagithub.com ↗HEAD 目錄 579 個序列化物件,每次 1.x.0 釋出後複製一份成 v1.34.0 等目錄,保證新程式碼還能讀舊資料。https://github.com/kubernetes/kubernetes/tree/765dd1d145814464051056c0eff14b7357eace82/staging/src/k8s.io/api/testdata ↩
-
Go Testing By Exampleresearch.swtch.com ↗GopherCon Australia 2023 演講的文字版:把測試用例寫成文字檔案、txtar、-update 重寫期望輸出。https://research.swtch.com/testing ↩
-
prometheus:promql/promqltest/testdatagithub.com ↗22 個 .test 檔案、2433 條 eval,Go 側只有 promqltest.RunBuiltinTests 一行。https://github.com/prometheus/prometheus/tree/a2fda0ef4638518a6a6fb27fc48be88fbd732f4b/promql/promqltest/testdata ↩
-
cockroachdb/datadrivengithub.com ↗測試檔案裡寫命令、輸入,---- 下面寫期望輸出;--rewrite 用實際輸出改寫檔案。https://github.com/cockroachdb/datadriven ↩
-
cockroach:pkg/sql/logictestgithub.com ↗testdata/logic_test 下 610 個 SQL 測試檔案,按 26 種叢集配置生成 generated_test.go,共 5764 個測試函式。https://github.com/cockroachdb/cockroach/tree/d30c905fff79ef825adc96bcc647f1872a90f2ff/pkg/sql/logictest ↩
-
golang/go:test/ 目錄與 cmd/internal/testdirgithub.com ↗3473 個給編譯器的測試程式,首行 // run、// errorcheck、// compile 等指令,由 go test cmd/internal/testdir 驅動。https://github.com/golang/go/tree/0d37007fda071631fbcb520b99c85a8e4c93108a/test ↩
-
golang/go:src/cmd/go/testdata/scriptgithub.com ↗951 個 txtar 格式的指令碼測試,go test cmd/go -run=Script/^foo$ 單獨跑一個。https://github.com/golang/go/tree/0d37007fda071631fbcb520b99c85a8e4c93108a/src/cmd/go/testdata/script ↩
-
hugo:testscriptsgithub.com ↗80 個 txtar 指令碼測試 hugo 命令列;hugolib 裡還有 418 處把整個站點寫成 txtar 字串的整合測試。https://github.com/gohugoio/hugo/tree/f63482bfbfe6aab81aaa198d9a006c7047f08d89/testscripts ↩
-
gitea:models/fixturesgithub.com ↗78 個 YAML 檔案,每個檔案是一張表的測試資料,測試前灌進 sqlite / MySQL / PostgreSQL。https://github.com/go-gitea/gitea/tree/ff68b39c93d7b0d10e0f6629fb188f8f1c0b37d4/models/fixtures ↩
-
kubernetes:client-go/kubernetes/fakegithub.com ↗client-gen 生成的假 clientset,是普通包,別的倉庫的測試也能 import。https://github.com/kubernetes/kubernetes/tree/765dd1d145814464051056c0eff14b7357eace82/staging/src/k8s.io/client-go/kubernetes/fake ↩
-
pingcap/failpointgithub.com ↗TiDB 的 make ut 先 failpoint-enable,把原始碼裡的 failpoint 標記改寫成可觸發的程式碼,跑完再還原。https://github.com/pingcap/failpoint ↩
-
cockroach:pkg/testutils/serverutils/test_server_shim.gogithub.com ↗“allow tests to set up test servers without importing the server package (avoiding circular dependencies)”,由 TestMain 注入 server.TestServerFactory。https://github.com/cockroachdb/cockroach/blob/d30c905fff79ef825adc96bcc647f1872a90f2ff/pkg/testutils/serverutils/test_server_shim.go ↩
延伸閱讀
- Advanced Testing with Gospeakerdeck.com ↗HashiCorp 的測試經驗:testdata、golden 檔案和 -update 開關、用子程序測試。https://speakerdeck.com/mitchellh/advanced-testing-with-go
- uber-go/goleakgithub.com ↗在 TestMain 或測試結束時檢查沒退出的 goroutine,k8s、Prometheus、TiDB 都在用。https://github.com/uber-go/goleak
- rogpeppe/go-internal:testscriptpkg.go.dev ↗從 cmd/go 的指令碼測試抽出來的獨立庫,hugo 用的就是它。https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript