Go 测试代码审查指南

审查工作流

请严格按以下顺序执行。在满足下方所有 通过条件（Pass） 之前，不得输出任何问题发现（findings）。

1. 基准 go.mod — 打开待审查模块的 go.mod 文件，读取其中的 go 指令。
   通过条件： 你能在审查前言或工作笔记中明确陈述该模块所声明的精确 go X.YY 版本号。仅当当前 go.mod 基准版本匹配时，才可应用版本限定的建议（例如：fuzz 测试要求 Go 1.18+；循环变量捕获问题存在于 Go 1.22 之前版本）。

2. 通读周边测试代码 — 对每个作用域内的 *_test.go（或 benchmark/fuzz 文件），须完整阅读其全部测试函数，以及它们所使用的 table-driven 结构体 struct{...} 和辅助函数，而不仅限于 diff 变更块。
   通过条件： 对每个作用域内的测试文件，至少完整阅读了一个包含变更的 func Test... / func Benchmark... / func Fuzz... 函数（或其调用的辅助函数）。

3. 划定检查清单适用范围 — 判断哪些《审查检查清单》条目适用于本次变更（例如：table-driven 结构、并发性、HTTP、golden 文件、mocks）。针对相关主题，打开 references/structure.md 和/或 references/mocking.md；对不适用于本次 diff 的条目，需逐条标注 N/A 并附简短原因（例如：“变更中无 t.Parallel 调用”）。
   通过条件： 审查报告（或工作笔记）中明确列出了已应用的检查清单主题，或对 N/A 主题给出了与 diff 直接关联的理由。

4. 报告前验证 — 加载并严格执行 review-verification-protocol。
   通过条件： 对你计划报告的每一项问题，均已完成协议中规定的 报告前验证检查清单（例如：实际阅读了对应测试代码、核查了上下文、区分了“错误”与“风格差异”等）。

硬性准入门禁（相同顺序，精简版）

输出格式

请按如下格式报告问题发现：

[FILE:LINE] ISSUE_TITLE
Severity: Critical | Major | Minor | Informational
问题描述及影响说明。

速查参考

审查检查清单

• 测试采用 table-driven 方式编写，且测试用例名称清晰明确
• 子测试使用 t.Run 实现并行执行
• 测试函数名描述行为语义，而非具体实现细节
• 错误断言包含 got/want 值及具描述性的消息
• 清理逻辑通过 t.Cleanup 注册
• 并行测试之间不共享可变状态
• Mock 实现使用定义在测试文件内的接口
• 测试覆盖边界情况与错误路径
• 性能关键函数配有 Benchmark* 测试
• 输入解析器/校验器配有 Fuzz* 测试（Go 1.18+）
• HTTP 处理器使用 httptest.NewRequest/httptest.NewRecorder 进行测试
• Golden 文件测试遵循 testdata/*.golden 命名约定，并支持 -update 标志

关键实践模式

Table-Driven 测试

// BAD - 重复冗余
func TestAdd(t *testing.T) {
    if Add(1, 2) != 3 {
        t.Error("wrong")
    }
    if Add(0, 0) != 0 {
        t.Error("wrong")
    }
}

// GOOD
func TestAdd(t *testing.T) {
    tests := []struct {
        name     string
        a, b     int
        want     int
    }{
        {"positive numbers", 1, 2, 3},
        {"zeros", 0, 0, 0},
        {"negative", -1, 1, 0},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got := Add(tt.a, tt.b)
            if got != tt.want {
                t.Errorf("Add(%d, %d) = %d, want %d", tt.a, tt.b, got, tt.want)
            }
        })
    }
}

错误消息

// BAD
if got != want {
    t.Error("wrong result")
}

// GOOD
if got != want {
    t.Errorf("GetUser(%d) = %v, want %v", id, got, want)
}

// 对于复杂类型
if diff := cmp.Diff(want, got); diff != "" {
    t.Errorf("GetUser() mismatch (-want +got):n%s", diff)
}

并行测试

func TestFoo(t *testing.T) {
    tests := []struct{...}

    for _, tt := range tests {
        tt := tt  // 显式捕获（Go 1.22+ 已无需此步）
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()
            // 测试逻辑
        })
    }
}

清理逻辑

// BAD - 手动清理，在 panic 时被跳过
func TestWithTempFile(t *testing.T) {
    f, _ := os.CreateTemp("", "test")
    defer os.Remove(f.Name())  // 若测试 panic，此行将被跳过
}

// GOOD
func TestWithTempFile(t *testing.T) {
    f, _ := os.CreateTemp("", "test")
    t.Cleanup(func() {
        os.Remove(f.Name())
    })
}

其他推荐实践

性能基准测试（Benchmarks）

func BenchmarkProcess(b *testing.B) {
    data := generateTestData(1000)
    b.ResetTimer()

    for i := 0; i < b.N; i++ {
        Process(data)
    }
}

// 运行命令：go test -bench=BenchmarkProcess -benchmem

Fuzz 测试（Go 1.18+）

func FuzzParseInput(f *testing.F) {
    // 初始化语料库
    f.Add(`{"name": "test"}`)
    f.Add(``)
    f.Add(`{invalid}`)

    f.Fuzz(func(t *testing.T, input string) {
        result, err := ParseInput(input)
        if err != nil {
            return // 输入非法属于预期行为
        }
        // 若解析成功，则重新序列化应无错误
        if _, err := json.Marshal(result); err != nil {
            t.Errorf("Marshal after Parse: %v", err)
        }
    })
}

// 运行命令：go test -fuzz=FuzzParseInput -fuzztime=30s

HTTP 处理器测试

func TestHandler(t *testing.T) {
    srv := NewServer(mockDeps)

    req := httptest.NewRequest("GET", "/api/users/123", nil)
    w := httptest.NewRecorder()

    srv.ServeHTTP(w, req)

    if w.Code != http.StatusOK {
        t.Errorf("status = %d, want %d", w.Code, http.StatusOK)
    }
}

Golden 文件测试

var update = flag.Bool("update", false, "update golden files")

func TestRender(t *testing.T) {
    got := Render(input)
    golden := filepath.Join("testdata", t.Name()+".golden")

    if *update {
        if err := os.WriteFile(golden, got, 0644); err != nil {
            t.Fatalf("writing golden file: %v", err)
        }
    }

    want, err := os.ReadFile(golden)
    if err != nil {
        t.Fatalf("reading golden file: %v (run with -update to create)", err)
    }
    if !bytes.Equal(got, want) {
        t.Errorf("output mismatch:ngot:n%snwant:n%s", got, want)
    }
}

反模式（Anti-Patterns）

1. 测试内部实现细节

// BAD - 测试私有字段
func TestUser(t *testing.T) {
    u := NewUser("alice")
    if u.id != 1 {  // 测试内部字段，违反封装
        t.Error("wrong id")
    }
}

// GOOD - 测试公开行为
func TestUser(t *testing.T) {
    u := NewUser("alice")
    if u.ID() != 1 {
        t.Error("wrong ID")
    }
}

2. 共享可变状态

// BAD - 测试间相互干扰
var testDB = setupDB()

func TestA(t *testing.T) {
    t.Parallel()
    testDB.Insert(...)  // 竞态风险！
}

// GOOD - 每个测试独占隔离实例
func TestA(t *testing.T) {
    db := setupTestDB(t)
    t.Cleanup(func() { db.Close() })
    db.Insert(...)
}

3. 缺乏上下文的断言

// BAD
assert.Equal(t, want, got)  // “expected X got Y” — 无法定位是哪个测试失败？

// GOOD
assert.Equal(t, want, got, "user name after update")

何时加载参考文档

• 审查测试文件结构时 → 查阅 structure.md
• 审查 mock 实现时 → 查阅 mocking.md

审查核心问题清单

1. 测试是否采用 table-driven 方式编写，且用例命名清晰？
2. 错误消息是否包含输入参数、实际值（got）和期望值（want）？
3. 并行测试是否完全隔离（无共享可变状态）？
4. 资源清理是否通过 t.Cleanup 统一管理？
5. 测试是否聚焦于验证行为（behavior），而非实现细节（implementation）？