Go testing.T.Run 怎样组织层级子测试

当一组 Go 测试只用一个 TestXxx 和一串 if 拼在一起时，失败信息往往只告诉你“这个测试失败了”，却没有把场景边界说清楚。testing.T.Run 的作用就是把一个测试拆成有名称的子测试：父测试负责组织，子测试负责一个具体场景，继续嵌套后还能形成可筛选的路径。

先看懂 T.Run 形成的层级名称

t.Run(name, func(t *testing.T) { ... }) 会创建一个命名子测试。假设顶层函数叫 TestOrder，里面再运行 "create" 和 "invalid" 两组，那么测试名可以理解为 TestOrder/create 和 TestOrder/invalid。继续嵌套时，每一级名称都会追加到路径中。

这个名称不是装饰信息，而是后续筛选测试的入口。官方文档说明，-run 使用与子测试层级相对应的斜杠分段正则表达式；因此命名时要优先写稳定、能表达场景的词，不要把随机 ID 或完整输入直接塞进名称。

把表格数据放进一级子测试

最常见的组织方式是先准备一组测试用例，再让每一行通过 t.Run 获得自己的名字。这样失败日志能直接指出 TestNormalize/trim_spaces 之类的场景，单独重跑时也不必复制一份测试函数。

package order_test

import "testing"

func normalizeCode(input string) string {
    // 示例只保留与测试组织有关的纯函数，便于每个子测试独立断言。
    return input
}

func TestNormalizeCode(t *testing.T) {
    cases := []struct {
        name string
        in   string
        want string
    }{
        {name: "already_normalized", in: "A-01", want: "A-01"},
        {name: "trim_spaces", in: " A-01 ", want: " A-01 "},
    }

    for _, tc := range cases {
        tc := tc // 中文说明：每轮复制用例，避免闭包引用同一个循环变量。
        t.Run(tc.name, func(t *testing.T) {
            got := normalizeCode(tc.in)
            if got != tc.want {
                t.Errorf("normalizeCode(%q) = %q; want %q", tc.in, got, tc.want)
            }
        })
    }
}

上例把“输入、期望值、名称”放在同一行，子测试函数只关心断言。示例中的 normalizeCode 没有真正改变字符串，是为了突出 Run 的组织方式；实际项目里应替换成被测函数。循环变量的显式复制也让代码在需要并行化或迁移到不同 Go 版本时更容易读懂。

用嵌套 T.Run 表达业务分组

当测试同时有“业务分组”和“具体用例”两个维度时，可以把分组放在外层，把用例放在内层。例如订单测试先按支付方式分组，再按输入状态区分成功和拒绝。嵌套只应该表达读者确实会使用的筛选维度，否则路径越长，维护成本越高。

func TestCheckout(t *testing.T) {
    groups := map[string][]struct {
        name string
        ok   bool
    }{
        "card": {
            {name: "authorized", ok: true},
            {name: "declined", ok: false},
        },
        "wallet": {
            {name: "authorized", ok: true},
        },
    }

    for method, cases := range groups {
        method, cases := method, cases // 中文说明：固定本层闭包使用的分组数据。
        t.Run(method, func(t *testing.T) {
            for _, tc := range cases {
                tc := tc // 中文说明：让内层子测试绑定当前场景。
                t.Run(tc.name, func(t *testing.T) {
                    // 中文说明：真实项目中在这里调用结算函数并检查 tc.ok。
                    if tc.ok && method == "" {
                        t.Fatal("支付方式不能为空")
                    }
                })
            }
        })
    }
}

这种写法产生类似 TestCheckout/card/authorized 的路径。外层 Run 可以包住一次分组级准备，父函数在所有子测试返回后再做组级清理；如果资源只属于单个场景，则把 t.Cleanup 放在内层，避免不同场景相互影响。

用 -run 按路径筛选场景

命名稳定后，筛选就变成一个简单的正则匹配问题。下面这些命令只展示筛选意图，不代表本文在本机运行过：

# 运行 TestCheckout 下的全部子测试
go test -run '^TestCheckout$'

# 只运行 card 分组下的场景
go test -run 'TestCheckout/card'

# 只运行 card/declined 这一条路径
go test -run 'TestCheckout/card/declined'

外层名称和每个子名称分别参与匹配，命令中的斜杠分段对应层级。名称包含正则特殊字符时，优先使用简单字母、数字、下划线和短横线；如果必须匹配特殊字符，就按 shell 和正则两层规则分别转义。不要为了筛选方便把整段 JSON 当测试名，这会让日志和命令都难以维护。

处理清理和并行子测试的边界

t.Cleanup 适合注册与当前测试作用域绑定的释放动作。对于并行子测试，父测试不会在子测试真正结束前返回，因此可以把组级清理放在外层；但并行测试之间仍然不能无保护地写同一个文件、环境变量或可变对象。

func TestHeaders(t *testing.T) {
    cases := []struct {
        name string
        want string
    }{
        {name: "json", want: "application/json"},
        {name: "text", want: "text/plain"},
    }

    for _, tc := range cases {
        tc := tc // 中文说明：并行前先固定当前用例，避免闭包引用同一个循环变量。
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            t.Cleanup(func() {
                // 中文说明：清理由当前子测试创建的临时资源，不触碰其他用例。
            })
            got := tc.want // 中文说明：示例把期望值作为待检查的响应头。
            if got == "" {
                t.Fatalf("header is empty")
            }
        })
    }
}

这里的关键不是“所有子测试都并行”，而是先确认每个用例是否拥有独立资源。若它们共用数据库连接、临时目录或环境变量，应在外层建立安全的隔离策略，或者保持串行。需要共享准备时，先把准备动作放到父测试，再让子测试只读取不会被修改的结果。

常见问题

t.Run 返回后父测试一定可以清理共享资源吗？

可以把父级清理放在子测试调用之后；对并行子测试，父级 Run 会等待该组的并行子测试完成后才返回。清理动作仍要覆盖子测试真实使用的资源范围。

为什么 -run 没有匹配到想要的子测试？

先用 go test -v 查看完整测试名，再检查正则的父级和子级斜杠分段。不要只凭代码里的函数名猜最终路径。

每一层都应该使用 t.Run 吗？

不应该。只有会改变读者理解、资源边界或筛选需求的维度才值得形成一层；无意义的包装会让命令更长，也让失败定位更慢。