Golang 可测试示例含函数 (Example Function)
示例函数类似于单元测试函数,但没有 *testing 类型的参数。编写示例函数也是很容易的:
- 创建对应的测试文件:在 Go 项目的源代码目录下创建一个新的文件(和被测代码文件在同一个包),以 _test.go 为后缀名。例如,要测试 net 包中 dial.go 中的方法,在 net 包中创建一个名字为 dial_test.go 或者 net_test.go 或者 example_test.go 文件,和单元测试文件是一样的。
- 编写示例函数:在测试文件中,编写一个以 Example 为前缀的函数,后面跟上一个或多个字符或字符组合来标识测试用例的名称(一般使用被测的对象的名称,例如包名称、函数名称、结构体名称等,也可以不跟上任何字符),没有任何参数。
- 在方法体中编写使用方式,将内容输出到标准输出。方法体的最后可以添加 “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 提倡的代码即文档的一个最佳实践,如果你还没有使用过,赶快使用起来吧。