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

相关推荐
码事漫谈8 小时前
以后人人都可以成为导演
后端
Resean02239 小时前
Spring 源码分析(二)配置类的解析与扫描
java·后端·spring
一只爱撸猫的程序猿9 小时前
五周、两个开源仓库、九次拦截之后:AI 时代程序员缺的到底是什么
人工智能·后端·开源
ShineWinsu9 小时前
对于Qt:QFormLayout常见属性以及方法的解析
开发语言·c++·qt·面试·客户端·表单·qformlayout
北城笑笑10 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
ServBay11 小时前
Local harness 将退役,VS Code 本地开发要不要搬到云端?
后端·ai编程·visual studio code
ashiho11 小时前
【LeetCode hot 100】3. 无重复字符的最长子串 (三种解法)
java·数据结构·后端·算法·leetcode·滑动窗口
张一凡9312 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
00后程序员12 小时前
iOS 实时活动怎么开发,Windows 上用 KXBuild 和 ActivityKit 写灵动岛
后端·ios
程序员cxuan12 小时前
推荐 10 个 WorkBuddy 中的邪修用法
人工智能·后端·程序员