4. 基础测试框架：testing 包核心用法

在 Go 语言生态中，testing 标准库是编写单元测试、基准测试和示例函数的唯一官方基础设施。对于《Go 权限审计网关单测夹具》课程而言，掌握 testing 包的核心用法是构建一切夹具与断言逻辑的基石。本章将深入剖析 Test 函数签名、t *testing.T 的常用方法，并通过对比表格与流程图，帮助你建立清晰、可复用的测试编写规范。

4.1 Test 函数签名与执行规则

每个 Go 测试文件（_test.go）中的测试函数必须遵循以下签名规则：

func TestXxx(t *testing.T) {
    // 测试逻辑
}

关键约束条件：

  • 函数名必须以 Test 开头，后续部分首字母大写（驼峰命名）。
  • 参数固定为 t *testing.T，用于控制测试状态与日志输出。
  • 文件必须属于 package xxx_test（外部测试包）或与被测包同名（内部测试包）。
  • 测试函数无返回值，通过 t.Error/t.Fatal 等方法标记失败。
最佳实践：在权限审计网关项目中，建议使用外部测试包（package gateway_test）来模拟真实调用方视角，避免依赖包内未导出符号。

4.2 t *testing.T 常用方法分类

t *testing.T 提供了三类核心方法：失败报告、日志输出和测试控制。以下表格按使用频率与语义进行归类：

类别 方法签名 行为描述 典型场景
失败报告 t.Error(args ...any) 记录失败日志，继续执行当前测试函数 断言多个条件，希望收集所有失败点
t.Fatal(args ...any) 记录失败日志，立即终止当前 goroutine 前置条件失败，后续测试无意义（如数据库连接失败）
格式化失败 t.Errorf(format string, args ...any) 格式化输出失败信息，继续执行 需要动态拼接错误描述时
t.Fatalf(format string, args ...any) 格式化输出失败信息，立即终止 关键断言失败，需立即退出
日志输出 t.Log(args ...any) 记录普通日志，仅测试失败或 -v 时显示 调试中间变量、记录测试步骤
t.Logf(format string, args ...any) 格式化日志输出 结构化打印请求/响应内容
测试控制 t.Skip(args ...any) 跳过当前测试，标记为 SKIP 环境依赖不满足时（如未配置审计服务地址）
子测试 t.Run(name string, f func(t *testing.T)) 启动一个子测试，支持嵌套与并行 表驱动测试、多场景分组
并行控制 t.Parallel() 标记测试可与其他并行测试同时运行 无状态、无共享资源的独立测试
常见陷阱：在 t.Fatal 或 t.Fatalf 之后，当前测试函数会立即退出，但 defer 语句仍会执行。如果 defer 中调用了 t.Log，日志依然会被记录。请确保 defer 清理逻辑不依赖测试是否通过。

4.3 Errorf vs Fatalf：选择决策流程

在编写权限审计网关的测试时，正确选择 Errorf 与 Fatalf 直接影响测试的覆盖率与调试效率。以下流程图展示了决策路径：

Errorf vs Fatalf 决策流程 断言检查点 失败是否可恢复？ 是 t.Errorf 否 t.Fatalf 结果：继续收集更多失败 vs 立即终止 Errorf 适合多断言场景；Fatalf 适合前置条件失败 示例：审计规则加载失败 → Fatalf；单条规则校验不通过 → Errorf

4.4 Logf 的调试价值与输出控制

t.Logf 是测试过程中最灵活的“探针”。与 fmt.Printf 不同，t.Logf 的输出受 go test -v 标志控制：

  • 默认行为：仅当测试失败时，t.Logf 的内容才会被打印到标准输出。
  • 详细模式：使用 go test -v 时，所有 t.Logf 输出都会实时显示，适合调试复杂夹具。
  • 与 t.Error 配合：在 t.Errorf 之前使用 t.Logf 打印上下文，可以大幅提升失败信息的可读性。
权限审计网关实战案例：在测试“令牌解析”夹具时，使用 t.Logf("Token payload: %+v", payload) 记录解析结果。当断言失败时，日志自动输出，无需手动注释代码。

4.5 子测试与表驱动测试模式

t.Run 是构建可读性高、可并行执行的测试套件的核心工具。在权限审计网关中，表驱动测试是标准模式：

func TestAuditRuleValidation(t *testing.T) {
    tests := []struct {
        name    string
        rule    string
        wantErr bool
    }{
        {"valid_allow_rule", `{"action":"allow","path":"/api/v1/*"}`, false},
        {"invalid_json", `{bad json}`, true},
        {"missing_action", `{"path":"/api/v1/*"}`, true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            err := ValidateRule(tt.rule)
            if (err != nil) != tt.wantErr {
                t.Errorf("ValidateRule() error = %v, wantErr = %v", err, tt.wantErr)
            }
        })
    }
}

子测试的优势：

  • 独立命名：每个子测试有唯一名称，失败时快速定位。
  • 独立控制：每个子测试拥有自己的 t *testing.T，可单独调用 t.Parallel()。
  • 嵌套支持：子测试内可继续使用 t.Run，形成树状测试结构。

4.6 常用方法对比速查表

以下表格总结了 t *testing.T 最常用的 6 个方法，方便你在编写夹具时快速参考：

方法 是否终止 格式化 日志可见条件 推荐使用场景
t.Error 否 否 测试失败时 多断言收集
t.Errorf 否 是 测试失败时 带格式的多断言
t.Fatal 是 否 测试失败时 前置条件失败
t.Fatalf 是 是 测试失败时 带格式的前置失败
t.Log 否 否 -v 或失败时 调试信息
t.Logf 否 是 -v 或失败时 结构化调试

4.7 测试夹具中的典型错误模式

在权限审计网关的测试夹具开发中，以下三种错误模式最为常见，需要特别注意：

  1. 滥用 t.Fatal 导致测试覆盖率下降：在循环断言中使用 t.Fatal，一旦第一条数据失败，后续数据全部跳过。应改用 t.Error 收集所有失败。
  2. 忽略 t.Logf 的可见性：在调试阶段依赖 fmt.Printf 输出，导致 CI 环境中日志混乱。应统一使用 t.Logf，由 -v 标志控制输出。
  3. 子测试中共享变量闭包陷阱：在 t.Run 内部直接引用循环变量 tt，导致所有子测试使用最后一个测试用例。必须显式捕获：tt := tt。
闭包陷阱示例： 
// 错误写法
for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        // 这里 tt 指向循环变量，可能已被修改
    })
}

// 正确写法
for _, tt := range tests {
    tt := tt  // 显式捕获
    t.Run(tt.name, func(t *testing.T) {
        // 使用局部变量 tt
    })
}

4.8 本章小结

← 上一章 📖 返回目录 下一章 →