testing 运行并验证 示例 Running and validating

testing 包除了测试 还提供了运行并验证示例的功能 示例 一方面是文档的效果 是关于某个功能的使用例子
另一方面 可以 被当做测试运行
func ExampleHello() {
  fmt.Println("Hello")
  // Output: Hello
}
如果 Output: Hello 改为 Output: hello 运行测试会失败 提示：

got:
Hello
want:
hello

一个示例函数以 Example 开头
如果示例函数包含以 "Output" 开头的行注释 在运行测试时 go 会将示例函数的输出和 "Output" 注释中的值做比较 就如上面的例子
有时候 输出顺序可能不确定 比如循环输出 map 的值 那么可以使用 "Unordered output" 开头的注释
如果示例函数没有 "Output" 注释 该示例函数只会被编译而不会被运行


1.1. 命名约定
Go 语言通过 大量的 命名约定 来简化工具的复杂度 规范代码的风格 对示例函数的命名有如下约定

包级别的示例函数 直接命名为 func Example() { ... }
函数 F 的示例 命名为 func ExampleF() { ... }
类型 T 的示例 命名为 func ExampleT() { ... }
类型 T 上的 方法 M 的示例 命名为 func ExampleT_M() { ... }
想要给 包/类型/函数/方法 提供多个示例 可以通过在示例函数名称后附加一个不同的后缀来实现 但这种后缀必须以小写字母开头
func Example_suffix() { ... }
func ExampleF_suffix() { ... }
func ExampleT_suffix() { ... }
func ExampleT_M_suffix() { ... }
通常 示例代码会放在单独的示例文件中 命名为 example_test.go 可以查看 io 包中的 example_test.go 了解示例的编写

1.2. 实现原理
开头提到了示例的两个作用 它们分别是由 godoc 和 go test 这两个命令实现的
在执行 go test 时 会运行示例 具体的实现原理 可以通过阅读 go test 命令源码和 testing 包中 example.go 文件了解