testing

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.

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

Tests and benchmarks may be skipped if not applicable with a call to the Skip method of *T and *B:

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 its -bench flag is provided. Benchmarks are run sequentially.

For a description of the testing flags, see http://golang.org/cmd/go/#hdr-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. During benchark 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")
        }
    })
}

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 the package, a function F, a type T and method M on type T are:

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

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

func Example_suffix() { ... }
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.

Main

It is sometimes necessary for a test program to do extra setup or teardown before or after testing. It is also sometimes necessary for a test to control which code runs on the main thread. To support these and other cases, if a test file contains a function:

func TestMain(m *testing.M)

then the generated test will call TestMain(m) instead of running the tests directly. TestMain runs in the main goroutine and can do whatever setup and teardown is necessary around a call to m.Run. It should then call os.Exit with the result of m.Run.

The minimal implementation of TestMain is:

func TestMain(m *testing.M) { os.Exit(m.Run()) }

In effect, that is the implementation used when no TestMain is explicitly defined.

Index

• func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, ...)
• func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool)
• func Short() bool
• func Verbose() bool
• type InternalTest
• type M
  • func MainStart(matchString func(pat, str string) (bool, error), tests []InternalTest, ...) *M
  • func (m *M) Run() int
• 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) Log(args ...interface{})
  • func (c *T) Logf(format string, args ...interface{})
  • func (t *T) Parallel()
  • 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

Functions

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 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 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 M

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

M is a type passed to a TestMain function to run the actual tests.

func MainStart

func MainStart(matchString func(pat, str string) (bool, error), 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) Run

func (m *M) Run() int

Run runs the tests. It returns an exit code to pass to os.Exit.

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.

type TB

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{})
	Skip(args ...interface{})
	SkipNow()
	Skipf(format string, args ...interface{})
	Skipped() bool
	// contains filtered or unexported methods
}

TB is the interface common to T and B.