import "testing"
testing 提供对 Go 包的自动化测试的支持。通过 `go test` 命令，能够自动执行如下形式的任何函数：
func TestXxx(*testing.T)
其中 Xxx 可以是任何字母数字字符串（但第一个字母不能是 [a-z]），用于识别测试例程。
在这些函数中，使用 Error, Fail 或相关方法来发出失败信号。
要编写一个新的测试套件，需要创建一个名称以 _test.go 结尾的文件，该文件包含 `TestXxx` 函数，如上所述。 将该文件放在与被测试的包相同的包中。该文件将被排除在正常的程序包之外，但在运行 “go test” 命令时将被包含。 有关详细信息，请运行 “go help test” 和 “go help testflag” 了解。
如果有需要，可以调用 *T 和 *B 的 Skip 方法，跳过该测试或基准测试：
func TestTimeConsuming(t *testing.T) {
if testing.Short() {
t.Skip("skipping test in short mode.")
}
...
}
如下形式的函数：
func BenchmarkXxx(*testing.B)
被认为是基准测试，通过 "go test" 命令，加上 -bench flag 来执行。多个基准测试按照顺序运行。
testing flags 的详细描述, 参见 https://github.com/golang/go/blob/master/cmd/go/#hdr-Description_of_testing_flags.
基准测试函数样例看起来如下所示：
func BenchmarkHello(b *testing.B) {
for i := 0; i < b.N; i++ {
fmt.Sprintf("hello")
}
}
基准函数会运行目标代码 b.N 次。在基准执行期间，会调整 b.N 直到基准测试函数持续足够长的时间。输出
BenchmarkHello 10000000 282 ns/op
意味着循环执行了 10000000 次，每次循环花费 282 纳秒(ns)。
如果在运行前基准测试需要一些耗时的配置，则可以先重置定时器：
func BenchmarkBigLen(b *testing.B) {
big := NewBig()
b.ResetTimer()
for i := 0; i < b.N; i++ {
big.Len()
}
}
如果基准测试需要在并行设置中测试性能，则可以使用 RunParallel 辅助函数; 这样的基准测试一般与 go test -cpu 标志一起使用：
func BenchmarkTemplateParallel(b *testing.B) {
templ := template.Must(template.New("test").Parse("Hello, {{.}}!"))
b.RunParallel(func(pb *testing.PB) {
var buf bytes.Buffer
for pb.Next() {
buf.Reset()
templ.Execute(&buf, "World")
}
})
}
该包还运行并验证示例代码。示例函数可以包括以 "Output：" 开头的行注释，并在运行测试时与函数的标准输出进行比较。 （比较时会忽略前导和尾随空格。）这些是一个 example 的例子：
func ExampleHello() {
fmt.Println("hello")
// Output: hello
}
func ExampleSalutations() {
fmt.Println("hello, and")
fmt.Println("goodbye")
// Output:
// hello, and
// goodbye
}
"Unordered output:" 形式的注释，和 "Output:" 类似，但是能够以任意顺序匹配行：
func ExamplePerm() {
for _, value := range Perm(4) {
fmt.Println(value)
}
// Unordered output: 4
// 2
// 1
// 3
// 0
}
没有输出注释的示例函数被编译但不执行。
example 声明的命名约定：包，函数 F，类型 T，类型 T 上的方法 M 依次是：
func Example() { ... }
func ExampleF() { ... }
func ExampleT() { ... }
func ExampleT_M() { ... }
可以为 包/类型/函数/方法 提供多个 example 函数，这通过在名称上附加一个不同的后缀来实现。后缀必须是以小写字母开头。
func Example_suffix() { ... }
func ExampleF_suffix() { ... }
func ExampleT_suffix() { ... }
func ExampleT_M_suffix() { ... }
当一个文件包含一个示例函数，同时至少一个其他函数，类型，变量或常量声明，或没有测试或基准函数时，这个测试文件作为示例存在，通常命名为 example_test.go
T 和 B 的 Run 方法允许定义子单元测试和子基准测试，而不必为每个子测试和子基准定义单独的函数。这使得可以使用 Table-Driven 的基准测试和创建层级测试。它还提供了一种共享通用 setup 和 tear-down 代码的方法：
func TestFoo(t *testing.T) {
// <setup code>
t.Run("A=1", func(t *testing.T) { ... })
t.Run("A=2", func(t *testing.T) { ... })
t.Run("B=1", func(t *testing.T) { ... })
// <tear-down code>
}
每个子测试和子基准测试都有一个唯一的名称：顶级测试的名称和传递给 Run 的名称的组合，以斜杠分隔，并具有用于消歧的可选尾随序列号。
-run 和 -bench 命令行标志的参数是与测试名称相匹配的非固定的正则表达式。对于具有多个斜杠分隔元素（例如子测试）的测试，该参数本身是斜杠分隔的，其中表达式依次匹配每个名称元素。因为它是非固定的，一个空的表达式匹配任何字符串。例如，使用 "匹配" 表示 "其名称包含"：
go test -run '' # Run 所有测试。 go test -run Foo # Run 匹配 "Foo" 的顶层测试，例如 "TestFooBar"。 go test -run Foo/A= # 匹配顶层测试 "Foo"，运行其匹配 "A=" 的子测试。 go test -run /A=1 # 运行所有匹配 "A=1" 的子测试。
子测试也可用于控制并行性。所有的子测试完成后，父测试才会完成。在这个例子中，所有的测试是相互并行运行的，当然也只是彼此之间，不包括定义在其他顶层测试的子测试：
func TestGroupedParallel(t *testing.T) {
for _, tc := range tests {
tc := tc // capture range variable
t.Run(tc.Name, func(t *testing.T) {
t.Parallel()
...
})
}
}
在并行子测试完成之前，Run 方法不会返回，这提供了一种测试后清理的方法：
func TestTeardownParallel(t *testing.T) {
// This Run will not return until the parallel tests finish.
t.Run("group", func(t *testing.T) {
t.Run("Test1", parallelTest1)
t.Run("Test2", parallelTest2)
t.Run("Test3", parallelTest3)
})
// <tear-down code>
}
测试程序有时需要在测试之前或之后进行额外的设置（setup）或拆卸（teardown）。有时, 测试还需要控制在主线程上运行的代码。为了支持这些和其他一些情况, 如果测试文件包含函数:
func TestMain(m *testing.M)
那么生成的测试将调用 TestMain(m)，而不是直接运行测试。TestMain 运行在主 goroutine 中, 可以在调用 m.Run 前后做任何设置和拆卸。应该使用 m.Run 的返回值作为参数调用 os.Exit。在调用 TestMain 时, flag.Parse 并没有被调用。所以，如果 TestMain 依赖于 command-line 标志 (包括 testing 包的标记), 则应该显示的调用 flag.Parse。
一个简单的 TestMain 的实现：
func TestMain(m *testing.M) {
// call flag.Parse() here if TestMain uses flags
// 如果 TestMain 使用了 flags，这里应该加上 flag.Parse()
os.Exit(m.Run())
}
allocs.go benchmark.go cover.go example.go match.go testing.go
AllocsPerRun 返回在调用 f 期间内存平均分配次数。虽然返回值的类型为 float64，但它始终是一个整数值。
要计算分配次数，该函数将首先作为热身运行一次。然后将测量并返回指定数量（runs 参数）运行的内存平均分配次数。
AllocsPerRun 在测量过程中将 GOMAXPROCS 设置为1，并在返回前将其还原。
CoverMode reports what the test coverage mode is set to. The values are "set", "count", or "atomic". The return value will be empty if test coverage is not enabled.
Coverage reports the current code coverage as a fraction in the range [0, 1]. If coverage is not enabled, Coverage returns 0.
When running a large set of sequential test cases, checking Coverage after each one can be useful for identifying which test cases exercise new code paths. It is not a replacement for the reports generated by 'go test -cover' and 'go tool cover'.
func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample)
Main is an internal function, part of the implementation of the "go test" command. It was exported because it is cross-package and predates "internal" packages. It is no longer used by "go test" but preserved, as much as possible, for other systems that simulate "go test" using Main, but Main sometimes cannot be updated as new functionality is added to the testing package. Systems simulating "go test" should be updated to use MainStart.
RegisterCover records the coverage data accumulators for the tests. NOTE: This function is internal to the testing infrastructure and may change. It is not covered (yet) by the Go 1 compatibility guidelines.
func RunBenchmarks(matchString func(pat, str string) (bool, error), benchmarks []InternalBenchmark)
An internal function but exported because it is cross-package; part of the implementation of the "go test" command.
func RunExamples(matchString func(pat, str string) (bool, error), examples []InternalExample) (ok bool)
An internal function but exported because it is cross-package; part of the implementation of the "go test" command.
An internal function but exported because it is cross-package; part of the implementation of the "go test" command.
Short reports whether the -test.short flag is set.
Verbose reports whether the -test.v flag is set.
B 是传递给基准测试函数的一种类型，它用于管理基准测试的计时行为，并指示应该迭代地运行测试多少次。
一个基准测试在它的基准测试函数返回时，又或者在它的基准测试函数调用 FailNow、Fatal、Fatalf、SkipNow、Skip 或者 Skipf 中的任意一个方法时，测试即宣告结束。至于其他报告方法，比如 Log 和 Error 的变种，则可以在其他 goroutine 中同时进行调用。
跟单元测试一样，基准测试会在执行的过程中积累日志，并在测试完毕时将日志转储到标准错误。但跟单元测试不一样的是，为了避免基准测试的结果受到日志打印操作的影响，基准测试总是会把日志打印出来。
func (c *B) Error(args ...interface{})调用 Error 相当于在调用 Log 之后调用 Fail 。
调用 Errorf 相当于在调用 Logf 之后调用 Fail 。
func (c *B) Fail()
将当前的测试函数标识为“失败”，但仍然继续执行该函数。
func (c *B) FailNow()
将当前的测试函数标识为“失败”，并停止执行该函数。在此之后，测试过程将在下一个测试或者下一个基准测试中继续。 FailNow 必须在运行测试函数或者基准测试函数的 goroutine 中调用，而不能在测试期间创建的 goroutine 中调用。调用 FailNow 不会导致其他 goroutine 停止。
Failed 用于报告测试函数是否已失败。
func (c *B) Fatal(args ...interface{})调用 Fatal 相当于在调用 Log 之后调用 FailNow 。
调用 Fatalf 相当于在调用 Logf 之后调用 FailNow 。
func (c *B) Log(args ...interface{})Log 使用与 Println 相同的格式化语法对它的参数进行格式化， 然后将格式化后的文本记录到错误日志里面：
对于测试来说， 格式化文本只会在测试失败或者设置了 -test.v 标志的情况下被打印出来； 对于基准测试来说， 为了避免 -test.v 标志的值对测试的性能产生影响， 格式化文本总会被打印出来。
Log 使用与 Printf 相同的格式化语法对它的参数进行格式化， 然后将格式化后的文本记录到错误日志里面。 如果输入的格式化文本最末尾没有出现新行， 那么将一个新行添加到格式化后的文本末尾。
对于测试来说，Logf 产生的格式化文本只会在测试失败或者设置了 -test.v 标志的情况下被打印出来； 对于基准测试来说， 为了避免 -test.v 标志的值对测试的性能产生影响， Logf 产生的格式化文本总会被打印出来。
返回正在运行的测试或者基准测试的名字。
打开当前基准测试的内存统计功能，与使用 -test.benchmem 设置类似，但 ReportAllocs 只影响那些调用了该函数的基准测试。
对已经逝去的基准测试时间以及内存分配计数器进行清零。对于正在运行中的计时器，这个方法不会产生任何效果。
执行名字为 name 的子基准测试（subbenchmark）f ，并报告 f 在执行过程中是否出现了任何失败。
子基准测试跟其他普通的基准测试一样。一个调用了 Run 方法至少一次的基准测试将不会对其自身进行测量（measure），并且在 N 为 1 时， 这个基准测试将只会被执行一次。
Run 可以同时在多个 goroutine 中被调用，但这些调用必须发生在 b 的外部基准函数（outer benchmark function）返回之前。
以并行的方式执行给定的基准测试。 RunParallel 会创建出多个 goroutine ，并将 b.N 分配给这些 goroutine 执行， 其中 goroutine 数量的默认值为 GOMAXPROCS 。用户如果想要增加非CPU受限（non-CPU-bound）基准测试的并行性， 那么可以在 RunParallel 之前调用 SetParallelism 。RunParallel 通常会与 -cpu 标志一同使用。
body 函数将在每个 goroutine 中执行，这个函数需要设置所有 goroutine 本地的状态， 并迭代直到 pb.Next 返回 false 值为止。因为 StartTimer 、 StopTimer 和 ResetTimer 这三个函数都带有全局作用，所以 body 函数不应该调用这些函数；除此之外，body 函数也不应该调用 Run 函数。
Code:play
// Parallel benchmark for text/template.Template.Execute on a single object. testing.Benchmark(func(b *testing.B) { templ := template.Must(template.New("test").Parse("Hello, {{.}}!")) // RunParallel will create GOMAXPROCS goroutines // and distribute work among them. b.RunParallel(func(pb *testing.PB) { // Each goroutine has its own bytes.Buffer. var buf bytes.Buffer for pb.Next() { // The loop body is executed b.N times total across all goroutines. buf.Reset() templ.Execute(&buf, "World") } }) })
记录在单个操作中处理的字节数量。在调用了这个方法之后，基准测试将会报告 ns/op 以及 MB/s 。
将 RunParallel 使用的 goroutine 数量设置为 p*GOMAXPROCS ，如果 p 小于 1 ，那么调用将不产生任何效果。
CPU受限（CPU-bound）的基准测试通常不需要调用这个方法。
func (c *B) Skip(args ...interface{})调用 Skip 相当于在调用 Log 之后调用 SkipNow 。
func (c *B) SkipNow()
将当前测试标识为“被跳过”并停止执行该测试。 如果一个测试在失败（参考 Error 、 Errorf 和 Fail）之后被跳过了， 那么它还是会被判断为是“失败的”。
在停止当前测试之后， 测试过程将在下一个测试或者下一个基准测试中继续， 具体请参考 FailNow 。
SkipNow 必须在运行测试的 goroutine 中进行调用， 而不能在测试期间创建的 goroutine 中调用。 调用 SkipNow 不会导致其他 goroutine 停止。
调用 Skipf 相当于在调用 Logf 之后调用 SkipNow 。
报告测试是否已被跳过。
开始对测试进行计时。 这个函数在基准测试开始时会自动被调用， 它也可以在调用 StopTimer 之后恢复进行计时。
停止对测试进行计时。 当你需要执行一些复杂的初始化操作， 并且你不想对这些操作进行测量时， 就可以使用这个方法来暂时地停止计时。
type BenchmarkResult struct {
N int // The number of iterations.
T time.Duration // The total time taken.
Bytes int64 // Bytes processed in one iteration.
MemAllocs uint64 // The total number of memory allocations.
MemBytes uint64 // The total number of bytes allocated.
}基准测试运行的结果。
func Benchmark(f func(b *B)) BenchmarkResult
测试单个函数。用于创建不使用 "go test" 命令的自定义基准测试。
如果 f 调用 Run，则结果将是运行其所有子基准的结果估计，该子基准在单个基准测试中不会顺序调用 Run。
func (r BenchmarkResult) AllocedBytesPerOp() int64
func (r BenchmarkResult) AllocsPerOp() int64
func (r BenchmarkResult) MemString() string
func (r BenchmarkResult) NsPerOp() int64
func (r BenchmarkResult) String() string
type Cover struct {
Mode string
Counters map[string][]uint32
Blocks map[string][]CoverBlock
CoveredPackages string
}Cover records information about test coverage checking. NOTE: This struct is internal to the testing infrastructure and may change. It is not covered (yet) by the Go 1 compatibility guidelines.
CoverBlock records the coverage data for a single basic block. NOTE: This struct is internal to the testing infrastructure and may change. It is not covered (yet) by the Go 1 compatibility guidelines.
An internal type but exported because it is cross-package; part of the implementation of the "go test" command.
An internal type but exported because it is cross-package; part of the implementation of the "go test" command.
type M struct {
// contains filtered or unexported fields
}M 是传递给 TestMain 函数以运行实际测试的类型。
func MainStart(deps testDeps, tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) *M
MainStart is meant for use by tests generated by 'go test'. It is not meant to be called directly and is not subject to the Go 1 compatibility document. It may change signature from release to release.
Run 运行这些测试。它返回要传递给 os.Exit 的退出代码。
type PB struct {
// contains filtered or unexported fields
}PB 被 RunParallel 使用来运行并行基准测试。
Next 判断是否有更多的迭代要执行
type T struct {
// contains filtered or unexported fields
}T 是传递给测试函数的一种类型，它用于管理测试状态并支持格式化测试日志。测试日志会在执行测试的过程中不断累积， 并在测试完成时转储至标准输出。
当一个测试的测试函数返回时， 又或者当一个测试函数调用 FailNow 、 Fatal 、 Fatalf 、 SkipNow 、 Skip 或者 Skipf 中的任意一个时， 该测试即宣告结束。 跟 Parallel 方法一样， 以上提到的这些方法只能在运行测试函数的 goroutine 中调用。
至于其他报告方法， 比如 Log 以及 Error 的变种， 则可以在多个 goroutine 中同时进行调用。
func (c *T) Error(args ...interface{})调用 Error 相当于在调用 Log 之后调用 Fail 。
调用 Errorf 相当于在调用 Logf 之后调用 Fail 。
func (c *T) Fail()
将当前测试标识为失败，但是仍继续执行该测试。
func (c *T) FailNow()
将当前测试标识为失败并停止执行该测试，在此之后，测试过程将在下一个测试或者下一个基准测试中继续。
FailNow 必须在运行测试函数或者基准测试函数的 goroutine 中调用，而不能在测试期间创建的 goroutine 中调用。调用 FailNow 不会导致其他 goroutine 停止。
Failed 用于报告测试函数是否已失败。
func (c *T) Fatal(args ...interface{})调用 Fatal 相当于在调用 Log 之后调用 FailNow 。
调用 Fatalf 相当于在调用 Logf 之后调用 FailNow 。
func (c *T) Log(args ...interface{})Log 使用与 Println 相同的格式化语法对它的参数进行格式化，然后将格式化后的文本记录到错误日志里面：
1）对于测试来说，格式化文本只会在测试失败或者设置了 -test.v 标志的情况下被打印出来； 2）对于基准测试来说，为了避免 -test.v 标志的值对测试的性能产生影响， 格式化文本总会被打印出来。
Log 使用与 Printf 相同的格式化语法对它的参数进行格式化，然后将格式化后的文本记录到错误日志里面。 如果输入的格式化文本最末尾没有出现新行，那么将一个新行添加到格式化后的文本末尾。
1）对于测试来说，Logf 产生的格式化文本只会在测试失败或者设置了 -test.v 标志的情况下被打印出来； 2）对于基准测试来说，为了避免 -test.v 标志的值对测试的性能产生影响，Logf 产生的格式化文本总会被打印出来。
返回正在运行的测试或基准测试的名字。
Parallel 用于表示当前测试只会与其他带有 Parallel 方法的测试并行进行测试。
执行名字为 name 的子测试 f ，并报告 f 在执行过程中是否出现了任何失败。Run 将一直阻塞直到 f 的所有并行测试执行完毕。
Run 可以在多个 goroutine 里面同时进行调用，但这些调用必须发生在 t 的外层测试函数（outer test function）返回之前。
func (c *T) Skip(args ...interface{})调用 Skip 相当于在调用 Log 之后调用 SkipNow 。
func (c *T) SkipNow()
将当前测试标识为“被跳过”并停止执行该测试。 如果一个测试在失败（参考 Error、Errorf 和 Fail）之后被跳过了， 那么它还是会被判断为是“失败的”。
在停止当前测试之后，测试过程将在下一个测试或者下一个基准测试中继续，具体请参考 FailNow 。
SkipNow 必须在运行测试的 goroutine 中进行调用，而不能在测试期间创建的 goroutine 中调用。 调用 SkipNow 不会导致其他 goroutine 停止。
调用 Skipf 相当于在调用 Logf 之后调用 SkipNow 。
Skipped 用于报告测试函数是否已被跳过。
type TB interface {
Error(args ...interface{})
Errorf(format string, args ...interface{})
Fail()
FailNow()
Failed() bool
Fatal(args ...interface{})
Fatalf(format string, args ...interface{})
Log(args ...interface{})
Logf(format string, args ...interface{})
Name() string
Skip(args ...interface{})
SkipNow()
Skipf(format string, args ...interface{})
Skipped() bool
// contains filtered or unexported methods
}TB 是一个接口，类型 T 和 B 实现了该接口。
| Path | Synopsis |
|---|---|
| iotest | Package iotest implements Readers and Writers useful mainly for testing. |
| quick | Package quick implements utility functions to help with black box testing. |