Go语言测试示例编写教程

今天golang学习网给大家带来了《Go语言示例测试编写指南》，其中涉及到的知识点包括等等，无论你是小白还是老手，都适合看一看哦~有好的建议也欢迎大家在评论留言，若是看完有所收获，也希望大家能多多点赞支持呀！一起加油学习~

示例测试函数名必须以Example开头且无参数无返回值，用于生成文档代码片段并校验输出；需严格匹配// Output:注释内容，不支持testing.T操作，运行需显式指定-run标志。

示例测试函数名必须以 Example 开头

Go 的示例测试（Example test）不是用来验证逻辑正确性的，而是为文档提供可运行的、带输出的代码片段。它会被 go doc 和 godoc 工具自动提取展示，同时也能被 go test 执行并比对输出是否匹配注释末尾的 // Output: 行。

函数名必须严格满足：Example + 可选的驼峰命名（如 ExampleMapMerge），且不能带参数、不能有返回值。否则 go test 会直接忽略它。

• func Example() {} ✅ 合法，但无意义（没说明是哪个 API 的示例）
• func ExampleSortKeys() {} ✅ 推荐：清晰对应某个导出函数或类型
• func exampleSortKeys() {} ❌ 小写开头，不会被识别
• func ExampleSortKeys(t *testing.T) {} ❌ 有参数，会被跳过
• func ExampleSortKeys() int { return 0 } ❌ 有返回值，不合法

// Output: 必须紧贴函数体末尾，且内容要完全匹配

示例测试的输出校验非常严格：Go 运行时会捕获 fmt.Println 等标准输出，并与函数体最后一段以 // Output: 开头的注释逐行比对（包括空行和尾部空格）。

常见失败原因不是代码错，而是输出格式没对齐。比如：

func ExampleJoinStrings() {
	fmt.Println(strings.Join([]string{"a", "b", "c"}, "-"))
}
// Output:
// a-b-c

• 注释中 // Output: 和实际输出之间**不能有空行**（上面例子是合法的）
• 如果代码里是 fmt.Print("a-b-c")（无换行），而注释写的是 // a-b-c（隐含换行），就会失败 —— 因为 fmt.Print 不输出换行，但 // Output: 默认期望每行末尾有换行符
• 多行输出时，// Output: 后面的每一行都必须精确对应，包括缩进和空格。例如 fmt.Printf("%q", "hello") 输出 "hello"，若注释写成 // "hello" （末尾多一个空格），测试即失败

示例测试不能调用 t.Log 或 t.Error

示例函数签名不含 *testing.T，所以无法使用测试断言或日志。它只允许纯演示：构造输入 → 调用目标 API → 输出结果。

如果你需要验证中间状态、处理错误分支、或做条件判断，就不是示例测试该干的事 —— 那属于 TestXXX 函数的范畴。

• ✅ 允许：fmt.Println(json.Marshal(myStruct))
• ❌ 不允许：if err != nil { t.Fatal(err) }（编译不过）
• ❌ 不推荐：在示例里写 fmt.Println("error case:", err) 来“演示错误”，因为这会让 // Output: 变得脆弱且偏离文档初衷

真正想展示错误处理？单独写一个 ExampleXXXWithError，并在 // Output: 中明确写出错误字符串，前提是那确实是公开 API 合法且稳定的输出形式。

运行和调试示例测试要用 -run 和 -v

默认 go test 不运行示例测试；必须显式启用：

go test -run ^Example

加上 -v 可看到每个示例是否通过、实际输出是什么、预期输出是什么：

go test -v -run ^Example

• -run ^Example 是正则匹配，确保只跑示例函数（^ 表示开头，避免匹配到 TestExampleHelper 这类名字）
• 如果只想跑某一个，比如 ExampleSortKeys，写成 go test -v -run ExampleSortKeys
• 调试时输出不匹配？先手动运行示例函数（把内容复制到临时 main.go），看真实输出长什么样，再调整 // Output: 注释

别忘了：示例测试文件必须放在和被测代码同一包下，且文件名以 _test.go 结尾，否则 go test 根本不会加载它。

终于介绍完啦！小伙伴们，这篇关于《Go语言测试示例编写教程》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布Golang相关知识，快来关注吧！