Golang 中的可测试示例函数(Example Function)详解

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 提倡的代码即文档的一个最佳实践，如果你还没有使用过，赶快使用起来吧。

到此这篇关于Golang 中的可测试示例函数(Example Function)详解的文章就介绍到这了,更多相关Golang可测试示例函数内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！