func AllocsPerRun(runs int, f func()) (avg float64)
AllocsPerRun returns the average number of allocations during calls to f. Although the return value has type float64, it will always be an integral value.
To compute the number of allocations, the function will first be run once as a warm-up. The average number of allocations over the specified number of runs will then be measured and returned.
AllocsPerRun sets GOMAXPROCS to 1 during its measurement and will restore it before returning.
func CoverMode() string
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.
func Coverage() float64
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 Init()
Init registers testing flags. These flags are automatically registered by the "go test" command before running test functions, so Init is only needed when calling functions such as Benchmark without using "go test".
Init has no effect if it was already called.
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.
func RegisterCover(c Cover)
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)
RunBenchmarks is an internal function but exported because it is cross-package; it is part of the implementation of the "go test" command.
func RunExamples(matchString func(pat, str string) (bool, error), examples []InternalExample) (ok bool)
RunExamples is an internal function but exported because it is cross-package; it is part of the implementation of the "go test" command.
func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool)
RunTests is an internal function but exported because it is cross-package; it is part of the implementation of the "go test" command.
func Short() bool
Short reports whether the -test.short flag is set.
func Verbose() bool
Verbose reports whether the -test.v flag is set.
B is a type passed to Benchmark functions to manage benchmark timing and to specify the number of iterations to run.
A benchmark ends when its Benchmark function returns or calls any of the methods FailNow, Fatal, Fatalf, SkipNow, Skip, or Skipf. Those methods must be called only from the goroutine running the Benchmark function. The other reporting methods, such as the variations of Log and Error, may be called simultaneously from multiple goroutines.
Like in tests, benchmark logs are accumulated during execution and dumped to standard output when done. Unlike in tests, benchmark logs are always printed, so as not to hide output whose existence may be affecting benchmark results.
type B struct { N int // contains filtered or unexported fields }
func (c *B) Cleanup(f func())
Cleanup registers a function to be called when the test and all its subtests complete. Cleanup functions will be called in last added, first called order.
func (c *B) Error(args ...interface{})
Error is equivalent to Log followed by Fail.
func (c *B) Errorf(format string, args ...interface{})
Errorf is equivalent to Logf followed by Fail.
func (c *B) Fail()
Fail marks the function as having failed but continues execution.
func (c *B) FailNow()
FailNow marks the function as having failed and stops its execution by calling runtime.Goexit (which then runs all deferred calls in the current goroutine). Execution will continue at the next test or benchmark. FailNow must be called from the goroutine running the test or benchmark function, not from other goroutines created during the test. Calling FailNow does not stop those other goroutines.
func (c *B) Failed() bool
Failed reports whether the function has failed.
func (c *B) Fatal(args ...interface{})
Fatal is equivalent to Log followed by FailNow.
func (c *B) Fatalf(format string, args ...interface{})
Fatalf is equivalent to Logf followed by FailNow.
func (c *B) Helper()
Helper marks the calling function as a test helper function. When printing file and line information, that function will be skipped. Helper may be called simultaneously from multiple goroutines.
func (c *B) Log(args ...interface{})
Log formats its arguments using default formatting, analogous to Println, and records the text in the error log. For tests, the text will be printed only if the test fails or the -test.v flag is set. For benchmarks, the text is always printed to avoid having performance depend on the value of the -test.v flag.
func (c *B) Logf(format string, args ...interface{})
Logf formats its arguments according to the format, analogous to Printf, and records the text in the error log. A final newline is added if not provided. For tests, the text will be printed only if the test fails or the -test.v flag is set. For benchmarks, the text is always printed to avoid having performance depend on the value of the -test.v flag.
func (c *B) Name() string
Name returns the name of the running test or benchmark.
func (b *B) ReportAllocs()
ReportAllocs enables malloc statistics for this benchmark. It is equivalent to setting -test.benchmem, but it only affects the benchmark function that calls ReportAllocs.
func (b *B) ReportMetric(n float64, unit string)
ReportMetric adds "n unit" to the reported benchmark results. If the metric is per-iteration, the caller should divide by b.N, and by convention units should end in "/op". ReportMetric overrides any previously reported value for the same unit. ReportMetric panics if unit is the empty string or if unit contains any whitespace. If unit is a unit normally reported by the benchmark framework itself (such as "allocs/op"), ReportMetric will override that metric. Setting "ns/op" to 0 will suppress that built-in metric.
func (b *B) ResetTimer()
ResetTimer zeroes the elapsed benchmark time and memory allocation counters and deletes user-reported metrics. It does not affect whether the timer is running.
func (b *B) Run(name string, f func(b *B)) bool
Run benchmarks f as a subbenchmark with the given name. It reports whether there were any failures.
A subbenchmark is like any other benchmark. A benchmark that calls Run at least once will not be measured itself and will be called once with N=1.
func (b *B) RunParallel(body func(*PB))
RunParallel runs a benchmark in parallel. It creates multiple goroutines and distributes b.N iterations among them. The number of goroutines defaults to GOMAXPROCS. To increase parallelism for non-CPU-bound benchmarks, call SetParallelism before RunParallel. RunParallel is usually used with the go test -cpu flag.
The body function will be run in each goroutine. It should set up any goroutine-local state and then iterate until pb.Next returns false. It should not use the StartTimer, StopTimer, or ResetTimer functions, because they have global effect. It should also not call Run.
func (b *B) SetBytes(n int64)
SetBytes records the number of bytes processed in a single operation. If this is called, the benchmark will report ns/op and MB/s.
func (b *B) SetParallelism(p int)
SetParallelism sets the number of goroutines used by RunParallel to p*GOMAXPROCS. There is usually no need to call SetParallelism for CPU-bound benchmarks. If p is less than 1, this call will have no effect.
func (c *B) Skip(args ...interface{})
Skip is equivalent to Log followed by SkipNow.
func (c *B) SkipNow()
SkipNow marks the test as having been skipped and stops its execution by calling runtime.Goexit. If a test fails (see Error, Errorf, Fail) and is then skipped, it is still considered to have failed. Execution will continue at the next test or benchmark. See also FailNow. SkipNow must be called from the goroutine running the test, not from other goroutines created during the test. Calling SkipNow does not stop those other goroutines.
func (c *B) Skipf(format string, args ...interface{})
Skipf is equivalent to Logf followed by SkipNow.
func (c *B) Skipped() bool
Skipped reports whether the test was skipped.
func (b *B) StartTimer()
StartTimer starts timing a test. This function is called automatically before a benchmark starts, but it can also be used to resume timing after a call to StopTimer.
func (b *B) StopTimer()
StopTimer stops timing a test. This can be used to pause the timer while performing complex initialization that you don't want to measure.
func (c *B) TempDir() string
TempDir returns a temporary directory for the test to use. The directory is automatically removed by Cleanup when the test and all its subtests complete. Each subsequent call to t.TempDir returns a unique directory; if the directory creation fails, TempDir terminates the test by calling Fatal.
BenchmarkResult contains the results of a benchmark run.
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. // Extra records additional metrics reported by ReportMetric. Extra map[string]float64 }
func Benchmark(f func(b *B)) BenchmarkResult
Benchmark benchmarks a single function. It is useful for creating custom benchmarks that do not use the "go test" command.
If f depends on testing flags, then Init must be used to register those flags before calling Benchmark and before calling flag.Parse.
If f calls Run, the result will be an estimate of running all its subbenchmarks that don't call Run in sequence in a single benchmark.
func (r BenchmarkResult) AllocedBytesPerOp() int64
AllocedBytesPerOp returns the "B/op" metric, which is calculated as r.MemBytes / r.N.
func (r BenchmarkResult) AllocsPerOp() int64
AllocsPerOp returns the "allocs/op" metric, which is calculated as r.MemAllocs / r.N.
func (r BenchmarkResult) MemString() string
MemString returns r.AllocedBytesPerOp and r.AllocsPerOp in the same format as 'go test'.
func (r BenchmarkResult) NsPerOp() int64
NsPerOp returns the "ns/op" metric.
func (r BenchmarkResult) String() string
String returns a summary of the benchmark results. It follows the benchmark result line format from https://golang.org/design/14313-benchmark-format, not including the benchmark name. Extra metrics override built-in metrics of the same name. String does not include allocs/op or B/op, since those are reported by MemString.
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.
type Cover struct { Mode string Counters map[string][]uint32 Blocks map[string][]CoverBlock CoveredPackages string }
CoverBlock records the coverage data for a single basic block. The fields are 1-indexed, as in an editor: The opening line of the file is number 1, for example. Columns are measured in bytes. NOTE: This struct is internal to the testing infrastructure and may change. It is not covered (yet) by the Go 1 compatibility guidelines.
type CoverBlock struct { Line0 uint32 // Line number for block start. Col0 uint16 // Column number for block start. Line1 uint32 // Line number for block end. Col1 uint16 // Column number for block end. Stmts uint16 // Number of statements included in this block. }
InternalBenchmark is an internal type but exported because it is cross-package; it is part of the implementation of the "go test" command.
type InternalBenchmark struct { Name string F func(b *B) }
type InternalExample struct { Name string F func() Output string Unordered bool }
InternalTest is an internal type but exported because it is cross-package; it is part of the implementation of the "go test" command.
type InternalTest struct { Name string F func(*T) }
M is a type passed to a TestMain function to run the actual tests.
type M struct {
// contains filtered or unexported fields
}
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.
func (m *M) Run() (code int)
Run runs the tests. It returns an exit code to pass to os.Exit.
A PB is used by RunParallel for running parallel benchmarks.
type PB struct {
// contains filtered or unexported fields
}
func (pb *PB) Next() bool
Next reports whether there are more iterations to execute.
T is a type passed to Test functions to manage test state and support formatted test logs.
A test ends when its Test function returns or calls any of the methods FailNow, Fatal, Fatalf, SkipNow, Skip, or Skipf. Those methods, as well as the Parallel method, must be called only from the goroutine running the Test function.
The other reporting methods, such as the variations of Log and Error, may be called simultaneously from multiple goroutines.
type T struct {
// contains filtered or unexported fields
}
func (c *T) Cleanup(f func())
Cleanup registers a function to be called when the test and all its subtests complete. Cleanup functions will be called in last added, first called order.
func (t *T) Deadline() (deadline time.Time, ok bool)
Deadline reports the time at which the test binary will have exceeded the timeout specified by the -timeout flag.
The ok result is false if the -timeout flag indicates “no timeout” (0).
func (c *T) Error(args ...interface{})
Error is equivalent to Log followed by Fail.
func (c *T) Errorf(format string, args ...interface{})
Errorf is equivalent to Logf followed by Fail.
func (c *T) Fail()
Fail marks the function as having failed but continues execution.
func (c *T) FailNow()
FailNow marks the function as having failed and stops its execution by calling runtime.Goexit (which then runs all deferred calls in the current goroutine). Execution will continue at the next test or benchmark. FailNow must be called from the goroutine running the test or benchmark function, not from other goroutines created during the test. Calling FailNow does not stop those other goroutines.
func (c *T) Failed() bool
Failed reports whether the function has failed.
func (c *T) Fatal(args ...interface{})
Fatal is equivalent to Log followed by FailNow.
func (c *T) Fatalf(format string, args ...interface{})
Fatalf is equivalent to Logf followed by FailNow.
func (c *T) Helper()
Helper marks the calling function as a test helper function. When printing file and line information, that function will be skipped. Helper may be called simultaneously from multiple goroutines.
func (c *T) Log(args ...interface{})
Log formats its arguments using default formatting, analogous to Println, and records the text in the error log. For tests, the text will be printed only if the test fails or the -test.v flag is set. For benchmarks, the text is always printed to avoid having performance depend on the value of the -test.v flag.
func (c *T) Logf(format string, args ...interface{})
Logf formats its arguments according to the format, analogous to Printf, and records the text in the error log. A final newline is added if not provided. For tests, the text will be printed only if the test fails or the -test.v flag is set. For benchmarks, the text is always printed to avoid having performance depend on the value of the -test.v flag.
func (c *T) Name() string
Name returns the name of the running test or benchmark.
func (t *T) Parallel()
Parallel signals that this test is to be run in parallel with (and only with) other parallel tests. When a test is run multiple times due to use of -test.count or -test.cpu, multiple instances of a single test never run in parallel with each other.
func (t *T) Run(name string, f func(t *T)) bool
Run runs f as a subtest of t called name. It runs f in a separate goroutine and blocks until f returns or calls t.Parallel to become a parallel test. Run reports whether f succeeded (or at least did not fail before calling t.Parallel).
Run may be called simultaneously from multiple goroutines, but all such calls must return before the outer test function for t returns.
func (c *T) Skip(args ...interface{})
Skip is equivalent to Log followed by SkipNow.
func (c *T) SkipNow()
SkipNow marks the test as having been skipped and stops its execution by calling runtime.Goexit. If a test fails (see Error, Errorf, Fail) and is then skipped, it is still considered to have failed. Execution will continue at the next test or benchmark. See also FailNow. SkipNow must be called from the goroutine running the test, not from other goroutines created during the test. Calling SkipNow does not stop those other goroutines.
func (c *T) Skipf(format string, args ...interface{})
Skipf is equivalent to Logf followed by SkipNow.
func (c *T) Skipped() bool
Skipped reports whether the test was skipped.
func (c *T) TempDir() string
TempDir returns a temporary directory for the test to use. The directory is automatically removed by Cleanup when the test and all its subtests complete. Each subsequent call to t.TempDir returns a unique directory; if the directory creation fails, TempDir terminates the test by calling Fatal.
TB is the interface common to T and B.
type TB interface { Cleanup(func()) Error(args ...interface{}) Errorf(format string, args ...interface{}) Fail() FailNow() Failed() bool Fatal(args ...interface{}) Fatalf(format string, args ...interface{}) Helper() Log(args ...interface{}) Logf(format string, args ...interface{}) Name() string Skip(args ...interface{}) SkipNow() Skipf(format string, args ...interface{}) Skipped() bool TempDir() string // contains filtered or unexported methods }