测试文件里那几个函数,各自管什么

难度 ★★★☆☆ · 前置:包怎么分层,看的是依赖的方向 | 一句话结论:同一份测试文件里,Test 管对错,子测试管定位,Benchmark 管成本,Example 管输出,入口形状不同,跑法和那一屏输出也就完全不同。

写了两年多的测试文件,我对这几个函数一直有个没想清楚的地方。calc 这个包小得很,一个 Add,一个 Subtract,加起来十来行,我把它当成一块试验田,把 Go 测试文件里能出现的几类函数一次全塞进去,普通测试、带子测试的测试、基准、示例,一样来一个,然后一条命令一条命令地跑,把输出抄下来对着看。那几天终端里来回敲的就那么几条,先 go test 看它认不认,再 go test -v 看名字和层级,接着 go test -run 把一条单独摘出来,go test -cover 看百分比,最后 go test -bench 把基准和那两列内存一起打出来,每跑一条就把整屏输出粘进同一个文本文件,上下挨着排,回头对照着读。动手之前我的印象是糊的,知道它们都住在 _test.go 里,知道 go test 会把它们都跑一遍,可谁在什么阶段跑、谁的数字算进覆盖率、谁的输出会进 -v 那一屏,我答不上来。

我原本以为这只是叫法上的差别,四个前缀,四种习惯,跑起来应该都差不多。这一轮跑完才发现不是,前缀之后那一屏输出、那条命令认不认它、它算不算进覆盖率,三件事全都跟着前缀走,几个顺手就写过去的地方这才显出形状。四类函数住在一个文件里,各管一段,分开看每条规则都不难,凑在一起才知道它们不是同一套东西。

它们的入口形状不一样,参数类型不一样,跑起来的时机也不一样,混在同一个文件里,光看代码分不出各自归哪一档。

先看形状,再看跑法。

文件名以 _test.go 结尾,才会被编进来

文件名这条规则是硬的,必须以 _test.go 结尾,否则 go test 根本不把它编进来,不报错,也没有任何提示,它就安安静静躺在目录里,你以为测试在跑,那几条用例其实从来没执行过。

1
2
3
4
5
6
7
8
9
package calc

import "testing"

func TestAdd(t *testing.T) {
if got := Add(1, 2); got != 3 {
t.Fatalf("Add(1, 2) = %d, want 3", got)
}
}

名字这块有两道关,一道在文件名,一道在函数名,规则细到很容易记混。

位置 规则 反例(什么都不报,只是不被认)
文件名 必须以 _test.go 结尾 add_test.go.bak、addtest.go
函数名 Test 紧跟的那一位必须是大写或非小写 testAdd、Testadd
参数 只能是 *testing.T func TestAdd(t int)

函数名的规则稍微松一点,Test 后面紧跟的那一位必须是大写字母或者非小写字母,中文、数字、下划线都算非小写,所以 Test_add 能跑,testAdd 不跑,Testadd 也不跑,三种写法看着差不多,只有一种会被认。名字里那个前缀不是装饰。三条凑齐,go test 才认它是一个测试函数,认了之后它才进编译,没认的那几条连语法错误都不会报出来。这条规则不报错,什么都不说,沉默比报错难发现,等覆盖率一直是零,才会回头去查文件名。我把这三道关抄在便签上贴过一阵,不是为了记,是为了在怀疑自己手滑的时候有个地方对一眼,省得又从头念代码。我头一次撞上是在另一个仓库里存文件的时候多带了一截后缀,编辑器还把它当普通文件高亮着,我以为那几条用例根本没写对,从头念了两遍才想起来看文件名。(那阵子我一直在断言那边找,文件名这两个字压根没进过脑子。)t 这个参数,我头一年只用了两个方法,t.Errorf 和 t.Fatalf,前者记一笔错接着往下跑,后者记一笔错立刻从这个函数返回,名字只差一个字母,跑出来的日志能差出半屏。

用久了才明白这点区别不是风格问题,同一个函数里后面的断言还要不要执行,就取决于你选哪一个。这个选择在排错时特别要紧,一个函数里有七八个断言,前面已经红了一条,后面的还跑不跑,决定了你这一次拿到的是半屏线索还是完整的一条链。用 Errorf 的时候后续检查照样跑,一个函数能一次报出好几处问题,日志长一点,但一趟就把话说完。用 Fatalf 就只报第一处,后面那一串全被跳过,日志看着短,漏掉的信息也多。什么时候用哪个,跟这段代码在失败之后还能不能安全地走下去有关,后面的步骤依赖前面那一步的结果,就该用 Fatalf,各条检查彼此独立,就该用 Errorf 让它们一次报完,省得改一个错再跑一遍。

(这条我到现在还是凭手感,动手前先问一句后面还用不用得上。)

TestAdd 下面挂两个子测试,斜杠就是路径

子测试的写法,就是把一段断言包进 t.Run,第一个参数是名字,第二个参数是函数,函数再收一个 *testing.T,拼接是框架做的,你写的时候只给后半截。

1
2
3
4
5
6
7
8
9
10
11
12
func TestAdd(t *testing.T) {
t.Run("basic", func(t *testing.T) {
if Add(1, 2) != 3 {
t.Fatalf("want 3")
}
})
t.Run("negative", func(t *testing.T) {
if Add(-1, -2) != -3 {
t.Fatalf("want -3")
}
})
}

名字会拼到父测试后面,中间加一个斜杠,所以 TestAdd 里那个叫 basic 的子测试,输出里是 TestAdd/basic。好处是名字成了路径的一部分,-v 打出来的那一屏天然分了层,一眼能看出哪几条属于同一个父测试。

子测试名字里的斜杠,为什么会变成一层目录?子测试名字里的斜杠会变成层级。

1
2
3
4
5
6
7
8
9
10
11
=== RUN   TestAdd
=== RUN TestAdd/basic
=== RUN TestAdd/negative
--- PASS: TestAdd (0.00s)
--- PASS: TestAdd/basic (0.00s)
--- PASS: TestAdd/negative (0.00s)
=== RUN TestSubtract
=== RUN ExampleAdd
--- PASS: ExampleAdd (0.00s)
PASS
ok calc 0.002s

t.Run 拿名字拼出一条斜杠路径。

嵌套再深一点,斜杠多几层,缩进也跟着多几级。拼接只在名字上做,层级是 t.Run 套出来的,所以同一个子测试被包在两层里,路径就长两截。

子测试的名字怎么起,我前半年起得很随便,test1、test2、case2,跑一遍全绿,看不出坏处。等到某天一条红了,输出里写着 TestAdd/test2,还得回源码里数它排第几个。

数错一次就白改一处。后来我把名字改成描述输入的那一小段,basic、negative、empty、single,红了的时候报错里带的那截本身就是一句话,不用再回源码对位置,-run 也能直接照着它抄下来用。

名字起得好不好,全绿的时候一点区别都没有,只有出问题那一次才开始算账。这份省下来的时间不在我写代码的时候,是在我半年后回来改这个包、已经完全忘了当时怎么想的时候。

那时候唯一还能依靠的就是名字和输出,源码反倒排在后面,名字是我留给自己的线索。t.Run 还有一个返回值,布尔,表示这个子测试过没过,我在需要按组汇总的地方用过一次,把结果收进一个切片,最后一次性打出来。

加个 -run,只跑名字对上的那几条

go test -v -run TestAdd 这条命令跑出来的东西,只有 TestAdd 和它那两个子测试,TestSubtract 和 ExampleAdd 都不出现。它匹配的是函数名,从 Test 后面那一段开始算,斜杠可以一路往下走到子测试。

1
go test -v -run TestAdd/basic

有一点容易误会,-run 只筛执行,不筛编译,包里所有测试文件照样全编进去,编译错误一个都躲不掉。那段完整输出里,TestSubtract 只有一行 RUN,底下没跟着 PASS 或者 FAIL,我头一次抄的时候以为它挂了,回头看是我自己把中间那几行跳过去了。

覆盖率 66.7% 说的是语句,不是分支

go test -cover 打出来的是 coverage: 66.7% of statements,这句话里每个词都得看。of statements 说的是语句覆盖率,一条语句算不算数,只看它这次有没有被执行到。

if 里包着的那几条语句,只有真的进去走了一遍才计数,条件两个方向都试过没有,它不关心。

覆盖率不看那一行值不值钱。

1
ok  	calc	0.002s	coverage: 66.7% of statements

一支分支里要是根本没有语句,那支就不会出现在分母里。所以它既不是分支覆盖率,也不是行覆盖率,三个数的分母都不一样,拿一个工具的百分比去跟另一个比,比出来的东西没有意义。

66.7% 落到 calc 上,是 Subtract 里有一支没被碰到,三条语句走通两条,剩下那一条空在那儿,报告里会把它单独标出来,连着源码行号一起给。

覆盖率我后来主要拿来看反方向。不是看那个总数,是看哪些语句一行都没走到,加 -coverprofile 落一个文件下来,用 go tool cover 排一遍,按百分比从低到高,最底下那几行就是没人碰过的地方。

多数时候能直接对上我心里那几个不敢改的函数。这个用法跟追求百分之多少没关系,它给的是清单,不是分数。一个包 66.7%,看着不高,要是那剩下的三成里全是不出错的边界,这个数字一点也不丢人。

基准的轮数由框架定,成本按 b.N 摊

基准函数的形状跟测试不一样,名字以 Benchmark 开头,参数是 *testing.B,函数体里写一个循环,循环次数用 b.N,跑多少轮不由我定。

1
2
3
4
5
func BenchmarkAdd(b *testing.B) {
for i := 0; i < b.N; i++ {
Add(1, 2)
}
}
1
2
3
4
BenchmarkAdd-32      1000000000    0.3170 ns/op    0 B/op    0 allocs/op
BenchmarkAddSlice-32 11415886 104.4 ns/op 48 B/op 1 allocs/op
PASS
ok calc 0.753s

框架先拿一个小一点的 N 试一遍,看这一轮够不够久,不够就放大,直到耗时落在它能量准的范围里,再把总时间摊到每次操作上除出来。所以那个迭代次数不是成绩,是这次测量选择的量程,同一个函数在慢一点的机器上会得到另一个次数,成本那一列才是要读的东西。我自己第一次看到 1000000000 这个数的时候还愣了一下,以为是它跑得快才堆上去的,其实是快才需要堆这么多轮才量得准,慢的函数几百轮就够了,轮数不归我管。

BenchmarkAdd-32 那一行里的 32 是 GOMAXPROCS,1000000000 是这一轮堆上去的迭代次数,0.3170 ns/op 是摊到每次调用上的时间,后面两列是 -benchmem 加上去的,0 B/op 和 0 allocs/op 说的是这次操作没在堆上要过内存。

这两个数字要放在一起看,0.3170 ns/op 快得没什么实感,单看它意义有限,真能带走的是后面那两列。48 B 说明这次调用在堆上要了一块内存,一次分配说明每次都要(这种函数放进热路径),GC 的压力就是这么一点点攒起来的,单次看不出来,乘上一个请求里被调用的次数就不一样了。0 B/op 那一列还能反过来验证逃逸,同一个函数,参数从值改成指针,或者让它返回内部切片的某一段,这两列就会从零变成正数,编译器怎么判断的,不翻汇编也能看见个大概。

基准量的又是单次操作的成本,不含真实并发,也不含排队和调度,把它当成上限看,比当成承诺看稳当。

Example 靠 Output 注释对账,对不上就 FAIL

示例函数的形状最特别,名字以 Example 开头,函数体末尾留一行 // Output: 注释,后面写上你认为该打印出来的东西,缺了这行注释框架连跑都不跑。跑测试的时候它会真的把这个函数执行一遍,把它写到标准输出的内容抓下来,去掉首尾空行,跟你写的那几行逐行比。它不能指定比哪一段,抓的是全部输出,函数里多打一行调试信息,对账立刻就对不上。

这个约束听着碍事,用起来反而有用,它逼着我把那几行输出当成合同来写,写下来意味着我确认过这个函数对外该长什么样,不是跑通就算完。

我故意把期望值写错一个数字,屏幕上是两段,一段 got 下面写着 5,一段 want 下面写着 6,FAIL 排在最前面,最后落下 exit status 1 和那行 FAIL calc 0.000s,两边并排摆着,差在哪个字符上一眼就能看出来。

(我一开始还等着一行带行号的报错,等来的就是这两段。)对不上就是没对上,没有断言库,没有匹配器,就是逐行比文本,一行都糊弄不过去。

示例函数还有一个身份,godoc 会把它当成包文档的一部分展示,写对了等于给自己留了一份能跑的说明书,写错了就是一份会骗人的说明书,这大概也是它非跑不可的理由。

1
2
3
4
func ExampleAdd() {
fmt.Println(Add(2, 3))
// Output: 5
}
1
2
3
4
5
6
7
8
--- FAIL: ExampleAdd (0.00s)
got:
5
want:
6
FAIL
exit status 1
FAIL calc 0.000s

PAUSE 和 CONT 是并行子测试留下的脚印

t.Parallel() 加在两个子测试上之后,-v 那一屏变了样,两个子测试的位置上出现 PAUSE 和 CONT,交替着来,顺序不再是源码里的顺序,谁先抢到谁先跑。

原因是子测试调到 t.Parallel 的时候先把自己挂起,把控制权还给父测试,父测试等自己下面那几条都挂起完了,才一起放行,放行的动作就是打一行 CONT。它省的是总时长,不是 CPU,单个子测试该跑多久还是多久。

这套写法以前还有个坑,闭包抓到的是循环变量本身,Go 1.22 之后才填上。

缓存、count 参数和 short 各挡掉一段浪费

剩下几条命令都跟时间有关。-race 把测试放到竞争检测器下面跑,这个包跑出来是 ok calc 1.021s,同一份代码不带它的那次是 0.002s。包太小,倍数不该拿来当结论,只能说明这一轮确实更慢。

另外它依赖 cgo,交叉编译的时候会卡在这一关,报出来的错跟竞争一点关系都没有,看着像环境没配好,那阵子我在环境变量里翻了一下午。

先跑一遍,再看那一屏。

-count=1 关的是结果缓存,同一个包、同样的输入、同样的参数,第二次跑会直接打一行 (cached),不真的执行,改代码或者改参数之后缓存才失效。

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

CI 里一般都得显式带上它,不然一次误判能安静一整天。那行 (cached) 混在一堆 ok 里,扫一眼很容易当成正常通过。

-short 是个约定,测试里用 testing.Short() 判断,短的跑,慢的跳过,它不会自己起作用,我不写那行判断,它就什么也不做,短的那批先跑完,长的那批留着。

到这里,一个测试文件里能放的东西就都过了一遍。Test 管对错,子测试管分组和定位,Benchmark 管成本,Example 管输出和文档,入口形状决定了跑法,也决定了那一屏输出里会有什么。