Go 博客

Go 语言中的可测试示例

Andrew Gerrand
2015 年 5 月 7 日

介绍

Godoc 示例 是 Go 代码片段，显示为包文档，并通过将其作为测试运行来进行验证。用户还可以访问包的 godoc 网页并单击关联的“运行”按钮来运行它们。

为包提供可执行的文档可以确保信息在 API 发生更改时不会过时。

标准库包含许多此类示例（例如，参见 strings 包）。

本文介绍如何编写自己的示例函数。

示例是测试

示例作为包测试套件的一部分进行编译（并可选地执行）。

与典型的测试一样，示例是位于包的 _test.go 文件中的函数。但是，与正常的测试函数不同，示例函数不带任何参数，并且以 Example 而不是 Test 开头。

reverse 包 是 Go 示例存储库 的一部分。以下示例演示了其 String 函数

package reverse_test

import (
    "fmt"

    "golang.org/x/example/hello/reverse"
)

func ExampleString() {
    fmt.Println(reverse.String("hello"))
    // Output: olleh
}

此代码可能位于 reverse 目录中的 example_test.go 中。

Go 包文档服务器 pkg.go.dev 在 String 函数的文档 旁边显示此示例

运行包的测试套件，我们可以看到示例函数在我们无需进一步安排的情况下执行

$ go test -v
=== RUN   TestString
--- PASS: TestString (0.00s)
=== RUN   ExampleString
--- PASS: ExampleString (0.00s)
PASS
ok      golang.org/x/example/hello/reverse  0.209s

输出注释

ExampleString 函数“通过”是什么意思？

在执行示例时，测试框架会捕获写入标准输出的数据，然后将输出与示例的“Output:”注释进行比较。如果测试的输出与其输出注释匹配，则测试通过。

为了查看失败的示例，我们可以将输出注释文本更改为明显不正确的内容

func ExampleString() {
    fmt.Println(reverse.String("hello"))
    // Output: golly
}

并再次运行测试

$ go test
--- FAIL: ExampleString (0.00s)
got:
olleh
want:
golly
FAIL

如果我们完全删除输出注释

func ExampleString() {
    fmt.Println(reverse.String("hello"))
}

则示例函数会被编译但不会执行

$ go test -v
=== RUN   TestString
--- PASS: TestString (0.00s)
PASS
ok      golang.org/x/example/hello/reverse  0.110s

没有输出注释的示例对于演示无法作为单元测试运行的代码（例如访问网络的代码）很有用，同时保证示例至少可以编译。

示例函数名称

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 会在 String 函数的文档旁边显示 ExampleString 示例。

可以通过使用以下划线后跟小写字母开头的后缀为给定标识符提供多个示例。这些示例都记录了 String 函数

func ExampleString()
func ExampleString_second()
func ExampleString_third()

更大的示例

有时我们需要不止一个函数才能编写一个好的示例。

例如，为了演示 sort 包，我们应该显示 sort.Interface 的实现。由于方法不能在函数体内部声明，因此示例除了示例函数之外还必须包含一些上下文。

为了实现这一点，我们可以使用“整个文件示例”。整个文件示例是一个以 _test.go 结尾的文件，其中包含恰好一个示例函数、没有测试或基准测试函数，以及至少一个其他包级声明。在显示此类示例时，godoc 会显示整个文件。

这是 sort 包中的一个整个文件示例

package sort_test

import (
    "fmt"
    "sort"
)

type Person struct {
    Name string
    Age  int
}

func (p Person) String() string {
    return fmt.Sprintf("%s: %d", p.Name, p.Age)
}

// ByAge implements sort.Interface for []Person based on
// the Age field.
type ByAge []Person

func (a ByAge) Len() int           { return len(a) }
func (a ByAge) Swap(i, j int)      { a[i], a[j] = a[j], a[i] }
func (a ByAge) Less(i, j int) bool { return a[i].Age < a[j].Age }

func Example() {
    people := []Person{
        {"Bob", 31},
        {"John", 42},
        {"Michael", 17},
        {"Jenny", 26},
    }

    fmt.Println(people)
    sort.Sort(ByAge(people))
    fmt.Println(people)

    // Output:
    // [Bob: 31 John: 42 Michael: 17 Jenny: 26]
    // [Michael: 17 Jenny: 26 Bob: 31 John: 42]
}

一个包可以包含多个整个文件示例；每个文件一个示例。查看 sort 包的源代码 以在实践中了解这一点。

结论

Godoc 示例是编写和维护代码作为文档的一种好方法。它们还提供了用户可以构建的可编辑、可工作、可运行的示例。使用它们！