Go语言内置的测试框架提供了多种测试类型，其中Example测试凭借其独特的特性，在文档生成和输出验证场景中发挥着不可替代的作用。它不仅能作为可运行的示例代码，还能自动校验输出结果是否符合预期，是Go项目质量保障的重要一环。
Example测试的核心用途
Example测试主要有三个核心用途，分别是文档示例、输出校验和测试覆盖补充。
- 文档示例：Example测试会被
go doc工具自动提取为包文档的示例代码，用户可以直接参考运行，比纯文字说明更直观。当Example测试关联了函数、类型或方法时，文档中会自动展示对应的示例代码。 - 输出校验：Example测试可以通过注释声明预期输出，测试运行时框架会自动对比实际输出和预期输出，不一致则判定测试失败，无需额外编写断言逻辑。
- 测试覆盖补充：对于一些对外暴露的API，Example测试可以覆盖常规单元测试难以触达的使用场景，补充测试覆盖率。
Example测试的输出行为规则
Example测试的输出行为遵循固定的匹配规则，理解这些规则是编写正确Example测试的基础。
基本输出匹配规则
Example测试函数内部通过fmt系列函数输出的内容，需要和函数末尾的// Output:注释块内容完全一致，包括换行和空格。框架会逐行对比实际输出和注释中的预期输出，完全一致则测试通过。
下面是一个简单的Example测试示例：
package main
import "fmt"
// 待测试的函数
func Add(a, b int) int {
return a + b
}
// ExampleAdd 是Add函数的Example测试
func ExampleAdd() {
fmt.Println(Add(1, 2))
fmt.Println(Add(3, 4))
// Output:
// 3
// 7
}
上述测试中，fmt.Println会输出两行内容，分别是3和7，和// Output:下方的两行内容完全匹配，因此测试会通过。
无输出场景的处理
如果Example测试函数没有任何输出，那么不需要添加// Output:注释，测试会默认通过。如果添加了// Output:但下方没有内容，框架会认为预期输出为空，此时如果函数有实际输出，测试会失败。
复杂输出验证策略
在实际开发中，经常会遇到多行输出、包含动态内容、输出顺序不确定等复杂场景，此时需要采用对应的验证策略。
多行输出的验证
多行输出只需要按照实际输出的行数，在// Output:下方逐行写出预期内容即可，注意每一行的缩进和实际输出的缩进保持一致。如果输出中包含空行，也需要在预期中对应位置保留空行。
package main
import "fmt"
func PrintMultiLine() {
fmt.Println("第一行")
fmt.Println()
fmt.Println("第三行")
}
func ExamplePrintMultiLine() {
PrintMultiLine()
// Output:
// 第一行
//
// 第三行
}
包含动态内容的输出验证
如果输出中包含时间戳、随机值等动态内容，直接写死预期输出会导致测试不稳定。此时可以通过固定动态内容的输入，或者调整函数逻辑让动态内容可预测。如果无法避免动态内容，可以改用常规单元测试，通过testing包的断言逻辑验证部分输出。
例如下面的场景，输出包含当前时间戳，直接写Example测试会不稳定：
package main
import (
"fmt"
"time"
)
func PrintTime() {
fmt.Println(time.Now().Format("2006-01-02"))
}
// 这种写法会因为时间变化导致测试失败
// func ExamplePrintTime() {
// PrintTime()
// // Output:
// // 2024-05-20
// }
此时可以调整函数，允许传入时间参数，让输出可预测：
package main
import (
"fmt"
"time"
)
func PrintTimeWithInput(t time.Time) {
fmt.Println(t.Format("2006-01-02"))
}
func ExamplePrintTimeWithInput() {
PrintTimeWithInput(time.Date(2024, 5, 20, 0, 0, 0, 0, time.UTC))
// Output:
// 2024-05-20
}
输出顺序不确定的验证
如果输出的内容顺序不确定，比如遍历map的输出，Example测试的固定输出匹配会失效。此时不建议使用Example测试验证这类场景，改用常规单元测试，通过排序后对比或者集合对比的方式验证输出。
Example测试的命名规范
Example测试的命名需要遵循固定规则，否则框架无法识别：
- 函数名必须以
Example开头 - 如果关联某个函数，命名为
Example函数名 - 如果关联某个类型，命名为
Example类型名 - 如果关联某个类型的方法，命名为
Example类型名_方法名 - 如果同一个函数/类型有多个Example测试，可以在末尾添加后缀，比如
ExampleAdd_second
符合命名规范的Example测试会被go doc正确关联到对应的API文档中，同时会被go test命令自动识别执行。
总结
Example测试是Go语言测试体系中兼具文档和验证能力的特殊测试类型，适合用于对外API的示例展示和稳定输出的校验。编写时需要注意输出匹配规则，针对复杂场景选择合适的验证策略，同时遵循命名规范让测试被正确识别。合理使用Example测试，可以同时提升项目文档质量和测试可靠性，是Go开发者需要掌握的重要技能。