Golang 中的可测试示例函数（Example Function）详解

Golang 可测试示例含函数 (Example Function)

示例函数类似于单元测试函数，但没有 *testing 类型的参数。编写示例函数也是很容易的：

1. 创建对应的测试文件：在 Go 项目的源代码目录下创建一个新的文件（和被测代码文件在同一个包），以 _test.go 为后缀名。例如，要测试 net 包中 dial.go 中的方法，在 net 包中创建一个名字为 dial_test.go 或者 net_test.go 或者 example_test.go 文件，和单元测试文件是一样的。
2. 编写示例函数：在测试文件中，编写一个以 Example 为前缀的函数，后面跟上一个或多个字符或字符组合来标识测试用例的名称（一般使用被测的对象的名称，例如包名称、函数名称、结构体名称等，也可以不跟上任何字符），没有任何参数。
3. 在方法体中编写使用方式，将内容输出到标准输出。方法体的最后可以添加 "Output:" 或 "Unordered output:" 注释，也可以不添加。如果添加了"Output:"注释，会将输出结果与注释进行精确比较。如果添加了"Unordered output:"注释，也会将输出与注释进行比较，但是会忽略行顺序。没有添加任何 output 注释，示例函数会被编译但不会被执行。

可测试示例含函数示例

以 json 格式校验工具 https://github.com/luduoxin/json-validator-go 为例，validator 包中的 scanner.go 文件中的关键函数 Valid 用于校验给定字符串是否 json 格式，对应的测试文件为 scanner_test.go，里面的示例函数为 ExampleValid，代码如下：

func ExampleValid() {
	fmt.Println(Valid([]byte("{}")))
	// output: true
}

运行看下效果：

=== RUN   ExampleValid
--- PASS: ExampleValid (0.00s)
PASS

看一个有多条输出结果的示例：

func ExampleValid() {
	fmt.Println(Valid([]byte("{}")))
	fmt.Println(Valid([]byte(`a:b`)))
	// output: true
	// false
}

运行看下效果：

=== RUN   ExampleValid
--- PASS: ExampleValid (0.00s)
PASS

看一个 "Unordered output:" 注释的示例：

func ExampleValid() {
	fmt.Println(Valid([]byte("{}")))
	fmt.Println(Valid([]byte(`{"a":"b"}`)))
	// Unordered output: true
	// true
}

运行看下效果：

=== RUN   ExampleValid
--- PASS: ExampleValid (0.00s)
PASS

看一个测试不通过的示例：

func ExampleValid() {
	fmt.Println(Valid([]byte("{}")))
	fmt.Println(Valid([]byte(`{"a":"b"}`)))
	// Unordered output: true
	// false
}

运行看下效果：

=== RUN   ExampleValid
--- FAIL: ExampleValid (0.00s)
got:
true
true

看一个没有 output 注释的示例：

func ExampleValid() {
	fmt.Println(Valid([]byte("{}")))
}

运行 go test 命令，此函数不会被执行。

上面测试通过的示例（运行结果为 PASS 的示例）的通过是什么意思呢？就是在执行示例时，测试框架捕获写入到标准输出的数据，然后与 "output:" 注释中的结果进行比较，如果匹配，则测试通过，否则测试不通过（结果为 FAIL）。

在 Godoc 中的展示

示例函数会在 Godoc 中作为对应函数的示例，看 Golang 官方的一张截图：

Godoc 使用命名约定将示例函数与包级标的识符关联起来。约定规则如下：

func ExampleFoo()     // documents the Foo function or type
func ExampleBar_Qux() // documents the Qux method of type Bar
func Example()        // documents the package as a whole

按照这个约定，Godoc 将在 Reverse 函数的文档旁边显示 ExampleReverse 示例。通过使用以下划线开头、后跟小写字母的后缀，可以为指定函数（或者包、结构体、方法等）提供多个示例。如下：

func ExampleReverse()
func ExampleReverse_second()
func ExampleReverse_third()

小结

本文详细讲解了 Golang 中的可测试示例函数， 可以很方便地转换为 Godoc 中可读性很强的文档，这也是 Golang 提倡的代码即文档的一个最佳实践，如果你还没有使用过，赶快使用起来吧。