Go test -run 正则为何没有匹配目标用例

go test -run 没有匹配到目标用例，通常不是正则引擎失效，而是匹配对象、子测试层级或命令行转义理解错了。先记住一个原则：-run 匹配的是测试、示例和模糊测试的名称，不是测试文件名；普通片段默认可以命中名称中的一部分。

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

-run 先在当前包的测试名称上匹配；如果表达式包含未转义的 /，它还会把表达式拆成多段，分别对应测试标识的层级。

先确认 -run 到底匹配什么

Go 测试函数需要使用 TestXxx 形式，-run 看到的名称通常就是去掉前缀后的测试标识，例如 TestUserCreate 对应 UserCreate。因此下面的命令可以匹配包含 User 的测试：

// 用两个测试名说明 -run 匹配的是测试标识，而不是 _test.go 文件名
func TestUserCreate(t *testing.T) {
	// 这里放创建用户的测试断言
}

func TestOrderCreate(t *testing.T) {
	// 这里放创建订单的测试断言
}

# 先列出当前包的顶层测试名，再决定 -run 的匹配片段
go test -list '.*'

# 匹配名称中包含 User 的测试；单引号避免 shell 改写正则字符
go test -run 'User'

如果你把 user_test.go 当成匹配对象，写成 go test -run 'user_test' 就很可能得到空结果。文件名只决定哪些测试源会参与构建，-run 不会按文件名筛选。

普通片段、锚定和大小写要分清

-run 使用正则表达式，而不是简单的完整字符串比较。没有锚定时，User 可以匹配 TestUserCreate 对应的 UserCreate；如果只想匹配一个完整名称，可以用 ^ 和 $ 限定范围。

# 说明三种常见选择范围：部分匹配、完整匹配、字符组匹配
go test -run 'User'                  # 命中名称中含 User 的测试
go test -run '^UserCreate$'          # 只命中完整名称 UserCreate
go test -run '^User(Create|Update)$' # 只命中两个明确名称

正则默认区分大小写，所以 user 不会自动命中 UserCreate。如果确实需要忽略大小写，可以使用 RE2 支持的 (?i)，但更建议优先写出与测试命名一致的表达式，减少误命中。

另一个常见误区是把完整函数名和 -run 的名称混用。你可以先用 go test -list '.*' 看实际列出的名称，再决定是否去掉 Test 前缀以及是否需要锚定。

子测试要用斜杠表达层级

表格驱动测试常用 t.Run 生成子测试。此时测试标识由父测试和子测试组成，-run 中的未转义斜杠用于分隔匹配层级。

// 子测试名称会成为 -run 的第二段匹配对象
func TestParse(t *testing.T) {
	for _, tc := range []struct {
		name string
		want string
	}{
		{name: "empty", want: ""},
		{name: "number", want: "42"},
	} {
		t.Run(tc.name, func(t *testing.T) {
			// 真实测试中在这里比较解析结果
		})
	}
}

# 只选择 TestParse 下名为 number 的子测试
go test -run '^Parse$/^number$'

# 选择 TestParse 下名称含 number 的子测试
go test -run 'Parse/number'

这里的 / 不是普通字符拼接。官方说明会按未转义的斜杠拆分正则，并把每一段用于对应的测试标识元素。如果只写 Parse/number 仍然没有结果，先检查子测试实际名称是否包含空格、大小写差异或额外的前缀。

匹配父测试时，Go 可能先运行父测试以发现子测试，即使子测试层级最终没有命中，也不应把父测试出现视为目标子测试已经执行。

没有匹配时按四个方向排查

• 包是否正确：go test -run ... 默认作用于当前目录；在模块根目录运行时，目标测试可能在子包中，需要先定位包或使用明确的包参数。
• 名称是否正确：用 go test -list '.*' 查看当前包的顶层名称，确认大小写、前缀、子测试名和特殊字符。
• 斜杠是否有意：想匹配普通字符 / 时需要考虑正则语义；想匹配子测试时则保留层级斜杠，并分别写父、子两段。
• shell 是否改写：把正则放入单引号，避免括号、美元符号或星号先被 shell 解释。Windows 环境还要留意命令行工具对引号的处理差异。

# 用 -list 只观察名称，不运行测试；再用 -run 执行精确目标
go test -list 'Parse'
go test -run '^Parse$/^number$' -count=1

# -count=1 用于明确关闭成功结果的缓存影响，不改变 -run 的匹配规则
go test -run '^Parse$/^number$' -count=1

-count=1 不是修复正则的开关，但在你反复调整用例、担心看到缓存结果时，可以让这次执行更容易判断。它解决的是缓存观察问题，不会让一个本来不匹配的表达式突然命中。

一套更稳的命令模板

排查时可以把命令拆成“观察名称”和“执行目标”两步。先确认名称，再逐步增加约束，通常比一开始写复杂正则更快定位问题：

# 第一步：确认当前包有哪些顶层测试
go test -list '.*'

# 第二步：先用宽匹配确认父测试存在
go test -run 'Parse'

# 第三步：确认子测试名称后再收窄到完整层级
go test -run '^Parse$/^number$' -count=1

如果第二步能命中、第三步为空，问题通常位于子测试名称或层级表达式；如果第一步就没有目标名称，优先检查当前包、测试函数命名和构建条件，而不是继续堆叠正则。

几个常见问题

为什么写了 Test 前缀却没有命中？

-run 的匹配对象通常不包含测试函数的 Test 前缀。先用 -list 看输出，再按实际名称写表达式。

为什么匹配子测试时父测试也出现了？

Go 需要运行匹配的父测试来发现子测试，因此父测试可能被启动；这不等于所有子测试都命中。真正的目标应由斜杠后的子测试表达式决定。

什么时候应该使用完整锚定？

当测试名相似、只想运行一个固定用例或 CI 命令必须稳定时，使用 ^名称$；临时排查多个相关用例时，使用较宽的片段更方便。

总结：把 -run 当成“对实际测试标识做正则筛选”的入口：先用 -list 观察名称，再确认包、大小写、锚定和子测试斜杠，最后用单引号保护命令。这样遇到空匹配时，问题就能落到具体边界，而不是反复修改一条看不懂的正则。