Go testing.T.Run 怎样让表驱动测试显示稳定名称

表驱动测试一旦用例变多，真正让人难受的往往不是断言，而是失败时只看到 TestParse/2。解决办法是把用例名称放进表结构，再把它作为 testing.T.Run 的第一个参数。这样名称会进入子测试层级，go test -v 能读懂，-run 也能按名称过滤。

官方地址：https://pkg.go.dev/testing

本文只讨论 Go 标准库 testing 中的 T.Run。下面的名称来自业务输入和期望结果，不依赖切片下标；如果名称包含斜杠，还要额外考虑 -run 的层级匹配规则。

先看 T.Run 怎样形成稳定的测试路径

T.Run(name, f) 会创建一个子测试。最终显示的名字通常由顶层测试名和各级子测试名用斜杠连接，例如 TestParse/empty-input。官方文档说明，子测试名组合成层级路径；名称重复时，测试框架还可能追加序号来消歧。

如果直接使用下标，输出只能告诉你“第几行表格失败”，而不能说明这行代表什么。下标还会随着用例插入、排序或删除而变化，不适合作为长期诊断入口。

给表驱动用例增加 Name 字段

把名称和输入、期望值放在同一条记录中，是最容易维护的做法。名称应描述用户场景或规则，而不是重复实现细节。

package parser_test

import (
	"strconv"
	"testing"
)

func parsePort(s string) (int, error) {
	// 示例只保留文章关注的测试结构，真实项目可替换成业务解析函数。
	return strconv.Atoi(s)
}

func TestParsePort(t *testing.T) {
	cases := []struct {
		name string
		input string
		want int
		wantErr bool
	}{
		{name: "valid/8080", input: "8080", want: 8080},
		{name: "invalid/text", input: "web", wantErr: true},
		{name: "empty-input", input: "", wantErr: true},
	}

	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			// 失败信息带上用例名之外的关键输入，方便定位数据边界。
			got, err := parsePort(tc.input)
			if (err != nil) != tc.wantErr {
				t.Fatalf("error = %v, wantErr = %v", err, tc.wantErr)
			}
			if err == nil && got != tc.want {
				t.Fatalf("got = %d, want = %d", got, tc.want)
			}
		})
	}
}

这段代码的关键不是字段名必须叫 name，而是名称跟着用例数据一起维护。以后新增“带前导空格”或“超范围端口”时，直接增加一条有语义的记录即可。

命名时避开重复和斜杠歧义

名称最好满足三个条件：同一测试函数内尽量唯一、读者不看表格也能猜到场景、不会把无关信息塞进名称。valid/8080 这样的写法可读，但斜杠会被 -run 当成层级分隔符。如果希望把它看成一个整体，可以把斜杠替换成短横线，或者在筛选时按层级分别匹配。

例如，用例名可以统一为 valid-port-8080、invalid-text、empty-input。不要把时间戳、随机数或 map 遍历结果放进名称，否则每次运行都可能改变，失败日志就难以复现。

用 -v 和 -run 按名称重跑

名称稳定后，先用详细输出确认层级，再用 -run 缩小范围。-run 接收的是匹配测试名称的正则表达式；子测试名称按斜杠分段匹配，所以完整路径和部分路径都可以使用。

# 查看每条表驱动用例的名称和结果
go test -v ./...

# 只运行 TestParsePort 下的空输入用例
go test -run '^TestParsePort$/empty-input$' -v ./...

# 运行名称中包含 invalid 的子测试
go test -run 'TestParsePort/invalid' -v ./...

命令中的正则锚点是为了减少误匹配；名称本身若含有正则特殊字符，还要在筛选表达式里进行转义。测试函数内部可以继续调用 t.Parallel()，但并行只影响完成顺序，不应改变用例名称。

几个容易踩到的边界

• 名称唯一性只在当前测试层级内有意义；相同子名称放在不同顶层测试下并不冲突，但完整路径不同。
• 并行子测试的执行完成顺序可能变化，所以稳定名称不能用来推断日志先后。
• 闭包里使用循环变量时，应让每个子测试拿到自己的用例值；名称稳定不能替代正确的数据绑定。
• 名称只用于诊断和筛选，不要把完整敏感输入、令牌或个人数据直接写入名称。

总结：让名称成为测试的诊断入口

表驱动测试的稳定名称可以归纳为三步：在用例表中保存业务语义名称，用 t.Run(tc.name, ...) 创建子测试，再用 -v 和 -run 按层级检查。名称不需要很长，但必须稳定、可读、可筛选。这样新增用例不会让旧失败日志失去参照，定位单条场景也不必数表格下标。

相关问题

为什么 T.Run 输出后面有序号？ 通常是同一层级名称重复时，测试框架为区分实例追加的消歧序号；应优先修正名称设计，而不是依赖序号。

名称里能不能使用斜杠？ 可以，但斜杠参与测试层级和 -run 匹配。若不需要层级语义，使用短横线更直接。

并行表驱动测试还需要稳定名称吗？ 需要。并行会改变执行时序，稳定名称反而更有助于从交错日志中识别具体用例。