Documentation

Overview

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 can be any alphanumeric string (but the first letter must not be in [a-z]) and serves to identify the test routine. These TestXxx routines should be declared within the package they are testing.

Tests and benchmarks may be skipped if not applicable like this:

func TestTimeConsuming(t *testing.T) {
    if testing.Short() {
        t.Skip("skipping test in short mode.")
    }
    ...
}

Benchmarks

Functions of the form

func BenchmarkXxx(*testing.B)

are considered benchmarks, and are executed by the "go test" command when the -test.bench flag is provided. Benchmarks are run sequentially.

For a description of the testing flags, see http://golang.org/cmd/go/#Description_of_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. The benchmark package will vary b.N 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()
    }
}

Examples

The package also runs and verifies example code. Example functions may include a concluding line comment that begins with "Output:" and is compared with the standard output of the function when the tests are run. (The comparison ignores leading and trailing space.) These are examples of an example:

func ExampleHello() {
        fmt.Println("hello")
        // Output: hello
}

func ExampleSalutations() {
        fmt.Println("hello, and")
        fmt.Println("goodbye")
        // Output:
        // hello, and
        // goodbye
}

Example functions without output comments are compiled but not executed.

The naming convention to declare examples for a function F, a type T and method M on type T are:

func ExampleF() { ... }
func ExampleT() { ... }
func ExampleT_M() { ... }

Multiple example functions for a type/function/method may be provided by appending a distinct suffix to the name. The suffix must start with a lower-case letter.

func ExampleF_suffix() { ... }
func ExampleT_suffix() { ... }
func ExampleT_M_suffix() { ... }

The entire test file is presented as the example when it contains a single example function, at least one other function, type, variable, or constant declaration, and no test or benchmark functions.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AllocsPerRun

func AllocsPerRun(runs int, f func()) (avg float64)

    AllocsPerRun returns the average number of allocations during calls to f.

    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 Main

    func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample)

      An internal function but exported because it is cross-package; part of the implementation of the "go test" command.

      func RunBenchmarks

      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

        func RunExamples(matchString func(pat, str string) (bool, error), examples []InternalExample) (ok bool)

        func RunTests

        func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool)

        func Short

        func Short() bool

          Short reports whether the -test.short flag is set.

          func Verbose

          func Verbose() bool

            Verbose reports whether the -test.v flag is set.

            Types

            type B

            type B struct {
            	N int
            	// contains filtered or unexported fields
            }

              B is a type passed to Benchmark functions to manage benchmark timing and to specify the number of iterations to run.

              func (*B) Error

              func (c *B) Error(args ...interface{})

                Error is equivalent to Log followed by Fail.

                func (*B) Errorf

                func (c *B) Errorf(format string, args ...interface{})

                  Errorf is equivalent to Logf followed by Fail.

                  func (*B) Fail

                  func (c *B) Fail()

                    Fail marks the function as having failed but continues execution.

                    func (*B) FailNow

                    func (c *B) FailNow()

                      FailNow marks the function as having failed and stops its execution. 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 (*B) Failed

                      func (c *B) Failed() bool

                        Failed reports whether the function has failed.

                        func (*B) Fatal

                        func (c *B) Fatal(args ...interface{})

                          Fatal is equivalent to Log followed by FailNow.

                          func (*B) Fatalf

                          func (c *B) Fatalf(format string, args ...interface{})

                            Fatalf is equivalent to Logf followed by FailNow.

                            func (*B) Log

                            func (c *B) Log(args ...interface{})

                              Log formats its arguments using default formatting, analogous to Println, and records the text in the error log. The text will be printed only if the test fails or the -test.v flag is set.

                              func (*B) Logf

                              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. The text will be printed only if the test fails or the -test.v flag is set.

                                func (*B) ReportAllocs

                                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) ResetTimer

                                  func (b *B) ResetTimer()

                                    ResetTimer sets the elapsed benchmark time to zero. It does not affect whether the timer is running.

                                    func (*B) SetBytes

                                    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) Skip

                                      func (c *B) Skip(args ...interface{})

                                        Skip is equivalent to Log followed by SkipNow.

                                        func (*B) SkipNow

                                        func (c *B) SkipNow()

                                          SkipNow marks the test as having been skipped and stops its execution. 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 (*B) Skipf

                                          func (c *B) Skipf(format string, args ...interface{})

                                            Skipf is equivalent to Logf followed by SkipNow.

                                            func (*B) Skipped

                                            func (c *B) Skipped() bool

                                              Skipped reports whether the test was skipped.

                                              func (*B) StartTimer

                                              func (b *B) StartTimer()

                                                StartTimer starts timing a test. This function is called automatically before a benchmark starts, but it can also used to resume timing after a call to StopTimer.

                                                func (*B) 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.

                                                  type BenchmarkResult

                                                  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.
                                                  }

                                                    The results of a benchmark run.

                                                    func Benchmark

                                                    func Benchmark(f func(b *B)) BenchmarkResult

                                                      Benchmark benchmarks a single function. Useful for creating custom benchmarks that do not use the "go test" command.

                                                      func (BenchmarkResult) AllocedBytesPerOp

                                                      func (r BenchmarkResult) AllocedBytesPerOp() int64

                                                      func (BenchmarkResult) AllocsPerOp

                                                      func (r BenchmarkResult) AllocsPerOp() int64

                                                      func (BenchmarkResult) MemString

                                                      func (r BenchmarkResult) MemString() string

                                                      func (BenchmarkResult) NsPerOp

                                                      func (r BenchmarkResult) NsPerOp() int64

                                                      func (BenchmarkResult) String

                                                      func (r BenchmarkResult) String() string

                                                      type InternalBenchmark

                                                      type InternalBenchmark struct {
                                                      	Name string
                                                      	F    func(b *B)
                                                      }

                                                        An internal type but exported because it is cross-package; part of the implementation of the "go test" command.

                                                        type InternalExample

                                                        type InternalExample struct {
                                                        	Name   string
                                                        	F      func()
                                                        	Output string
                                                        }

                                                        type InternalTest

                                                        type InternalTest struct {
                                                        	Name string
                                                        	F    func(*T)
                                                        }

                                                          An internal type but exported because it is cross-package; part of the implementation of the "go test" command.

                                                          type T

                                                          type T struct {
                                                          	// contains filtered or unexported fields
                                                          }

                                                            T is a type passed to Test functions to manage test state and support formatted test logs. Logs are accumulated during execution and dumped to standard error when done.

                                                            func (*T) Error

                                                            func (c *T) Error(args ...interface{})

                                                              Error is equivalent to Log followed by Fail.

                                                              func (*T) Errorf

                                                              func (c *T) Errorf(format string, args ...interface{})

                                                                Errorf is equivalent to Logf followed by Fail.

                                                                func (*T) Fail

                                                                func (c *T) Fail()

                                                                  Fail marks the function as having failed but continues execution.

                                                                  func (*T) FailNow

                                                                  func (c *T) FailNow()

                                                                    FailNow marks the function as having failed and stops its execution. 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 (*T) Failed

                                                                    func (c *T) Failed() bool

                                                                      Failed reports whether the function has failed.

                                                                      func (*T) Fatal

                                                                      func (c *T) Fatal(args ...interface{})

                                                                        Fatal is equivalent to Log followed by FailNow.

                                                                        func (*T) Fatalf

                                                                        func (c *T) Fatalf(format string, args ...interface{})

                                                                          Fatalf is equivalent to Logf followed by FailNow.

                                                                          func (*T) Log

                                                                          func (c *T) Log(args ...interface{})

                                                                            Log formats its arguments using default formatting, analogous to Println, and records the text in the error log. The text will be printed only if the test fails or the -test.v flag is set.

                                                                            func (*T) Logf

                                                                            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. The text will be printed only if the test fails or the -test.v flag is set.

                                                                              func (*T) Parallel

                                                                              func (t *T) Parallel()

                                                                                Parallel signals that this test is to be run in parallel with (and only with) other parallel tests.

                                                                                func (*T) Skip

                                                                                func (c *T) Skip(args ...interface{})

                                                                                  Skip is equivalent to Log followed by SkipNow.

                                                                                  func (*T) SkipNow

                                                                                  func (c *T) SkipNow()

                                                                                    SkipNow marks the test as having been skipped and stops its execution. 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 (*T) Skipf

                                                                                    func (c *T) Skipf(format string, args ...interface{})

                                                                                      Skipf is equivalent to Logf followed by SkipNow.

                                                                                      func (*T) Skipped

                                                                                      func (c *T) Skipped() bool

                                                                                        Skipped reports whether the test was skipped.

                                                                                        Directories

                                                                                        Path Synopsis
                                                                                        Package iotest implements Readers and Writers useful mainly for testing.
                                                                                        Package iotest implements Readers and Writers useful mainly for testing.
                                                                                        Package quick implements utility functions to help with black box testing.
                                                                                        Package quick implements utility functions to help with black box testing.