testing - 运行并验证示例

testing 包除了测试，还提供了运行并验证示例的功能。示例，一方面是文档的效果，是关于某个功能的使用例子；另一方面，可以被当做测试运行。

一个示例的例子如下：

func ExampleHello() {
    fmt.Println("Hello")
    // Output: Hello
}

如果 Output: Hello 改为：Output: hello，运行测试会失败，提示：

got:
Hello
want:
hello

一个示例函数以 Example 开头，如果示例函数包含以 “Output:” 开头的行注释，在运行测试时，go 会将示例函数的输出和 “Output:” 注释中的值做比较，就如上面的例子。

有时候，输出顺序可能不确定，比如循环输出 map 的值，那么可以使用 “Unordered output:” 开头的注释。

如果示例函数没有上述输出注释，该示例函数只会被编译而不会被运行。

命名约定

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 了解示例的编写。

实现原理

本节开头提到了示例的两个作用，它们分别是由 godoc 和 go test 这两个命令实现的。

在执行 go test 时，会运行示例。具体的实现原理，可以通过阅读 go test 命令源码和 testing 包中 example.go 文件了解。