testing

Package testing provides support for automated testing of Go packages. It is intended to be used in concert with the “go test” command, which automates execution of any function of the form

func TestXxx(*testing.T) where Xxx does not start with a lowercase letter. The function name serves to identify the test routine. Within these functions, use the Error, Fail or related methods to signal failure. To write a new test suite, create a file whose name ends _test.go that contains the TestXxx functions as described here. Put the file in the same package as the one being tested. The file will be excluded from regular package builds but will be included when the “go test” command is run. For more detail, run “go help test” and “go help testflag”. A simple test function looks like this:

func TestAbs(t *testing.T) {
    got := Abs(-1)
    if got != 1 {
        t.Errorf("Abs(-1) = %d; want 1", got)
    }
}

Benchmarks

Functions of the form func BenchmarkXxx(*testing.B) are considered benchmarks, and are executed by the "go test" command when its -bench flag is provided. Benchmarks are run sequentially.

For a description of the testing flags, see https://golang.org/cmd/go/#hdr-Testing_flags

A sample benchmark function looks like this:

func BenchmarkHello(b *testing.B) {
    for i := 0; i < b.N; i++ {
        fmt.Sprintf("hello")
    }
}

The benchmark function must run the target code b.N times. During benchmark execution, b.N is adjusted until the benchmark function lasts long enough to be timed reliably. The output BenchmarkHello 10000000 282 ns/op means that the loop ran 10000000 times at a speed of 282 ns per loop. If a benchmark needs some expensive setup before running, the timer may be reset:

func BenchmarkBigLen(b *testing.B) {
    big := NewBig()
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        big.Len()
    }
}
`

If a benchmark needs to test performance in a parallel setting, it may use the RunParallel helper function; such benchmarks are intended to be used with the go test -cpu flag:

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")
        }
    })
}

API

    func AllocsPerRun(runs int, f func()) (avg float64)
    func CoverMode() string
    func Coverage() float64
    func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample)
    func RegisterCover(c Cover)
    func RunBenchmarks(matchString func(pat, str string) (bool, error), benchmarks []InternalBenchmark)
    func RunExamples(matchString func(pat, str string) (bool, error), examples []InternalExample) (ok bool)
    func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool)
    func Short() bool
    func Verbose() bool

type B

    func (c *B) Error(args ...interface{})
    func (c *B) Errorf(format string, args ...interface{})
    func (c *B) Fail()
    func (c *B) FailNow()
    func (c *B) Failed() bool
    func (c *B) Fatal(args ...interface{})
    func (c *B) Fatalf(format string, args ...interface{})
    func (c *B) Helper()
    func (c *B) Log(args ...interface{})
    func (c *B) Logf(format string, args ...interface{})
    func (c *B) Name() string
    func (b *B) ReportAllocs()
    func (b *B) ResetTimer()
    func (b *B) Run(name string, f func(b *B)) bool
    func (b *B) RunParallel(body func(*PB))
    func (b *B) SetBytes(n int64)
    func (b *B) SetParallelism(p int)
    func (c *B) Skip(args ...interface{})
    func (c *B) SkipNow()
    func (c *B) Skipf(format string, args ...interface{})
    func (c *B) Skipped() bool
    func (b *B) StartTimer()
    func (b *B) StopTimer()

type BenchmarkResult

    func Benchmark(f func(b *B)) BenchmarkResult
    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
type CoverBlock
type InternalBenchmark
type InternalExample
type InternalTest
type M

    func MainStart(deps testDeps, tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) *M
    func (m *M) Run() int

type PB

    func (pb *PB) Next() bool

type T

    func (c *T) Error(args ...interface{})
    func (c *T) Errorf(format string, args ...interface{})
    func (c *T) Fail()
    func (c *T) FailNow()
    func (c *T) Failed() bool
    func (c *T) Fatal(args ...interface{})
    func (c *T) Fatalf(format string, args ...interface{})
    func (c *T) Helper()
    func (c *T) Log(args ...interface{})
    func (c *T) Logf(format string, args ...interface{})
    func (c *T) Name() string
    func (t *T) Parallel()
    func (t *T) Run(name string, f func(t *T)) bool
    func (c *T) Skip(args ...interface{})
    func (c *T) SkipNow()
    func (c *T) Skipf(format string, args ...interface{})
    func (c *T) Skipped() bool

type TB