testing

Documentation

Overview

The testing package provides support for automated testing of Go packages. It is intended to be used in concert with the “gotest” utility, 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.

Functions of the form

func BenchmarkXxx(*testing.B)

are considered benchmarks, and are executed by gotest when the -benchmarks flag is provided.

A sample benchmark function looks like this:

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

The benchmark package will vary b.N until the benchmark function lasts long enough to be timed reliably. The output

testing.BenchmarkHello	500000	      4076 ns/op

means that the loop ran 500000 times at a speed of 4076 ns per loop.

If a benchmark needs some expensive setup before running, the timer may be stopped:

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

Index

• Variables
• func Main(tests []Test)
• func Match(pattern string, b []byte) (matched bool, error string)
• func MatchString(pattern string, s string) (matched bool, error string)
• func RunBenchmarks(benchmarks []Benchmark)
• type B
  • func (b *B) ResetTimer()
  • func (b *B) SetBytes(n int64)
  • func (b *B) StartTimer()
  • func (b *B) StopTimer()
• type Benchmark
• type Regexp
  • func CompileRegexp(str string) (regexp *Regexp, error string)
  • func MustCompile(str string) *Regexp
  • func (re *Regexp) Execute(b []byte) (a []int)
  • func (re *Regexp) ExecuteString(s string) (a []int)
  • func (re *Regexp) Match(b []byte) bool
  • func (re *Regexp) MatchSlices(b []byte) (a [][]byte)
  • func (re *Regexp) MatchString(s string) bool
  • func (re *Regexp) MatchStrings(s string) (a []string)
• type T
  • func (t *T) Error(args ...interface{})
  • func (t *T) Errorf(format string, args ...interface{})
  • func (t *T) Fail()
  • func (t *T) FailNow()
  • func (t *T) Failed() bool
  • func (t *T) Fatal(args ...interface{})
  • func (t *T) Fatalf(format string, args ...interface{})
  • func (t *T) Log(args ...interface{})
  • func (t *T) Logf(format string, args ...interface{})
• type Test

Variables

var (
	ErrInternal            = "internal error"
	ErrUnmatchedLpar       = "unmatched ''"
	ErrUnmatchedRpar       = "unmatched ''"
	ErrUnmatchedLbkt       = "unmatched '['"
	ErrUnmatchedRbkt       = "unmatched ']'"
	ErrBadRange            = "bad range in character class"
	ErrExtraneousBackslash = "extraneous backslash"
	ErrBadClosure          = "repeated closure **, ++, etc."
	ErrBareClosure         = "closure applies to nothing"
	ErrBadBackslash        = "illegal backslash escape"
)

Error codes returned by failures to parse an expression.

Functions

func Main

func Main(tests []Test)

An internal function but exported because it is cross-package; part of the implementation of gotest.

func Match

func Match(pattern string, b []byte) (matched bool, error string)

Match checks whether a textual regular expression matches a byte slice. More complicated queries need to use Compile and the full Regexp interface.

func MatchString

func MatchString(pattern string, s string) (matched bool, error string)

MatchString checks whether a textual regular expression matches a string. More complicated queries need to use Compile and the full Regexp interface.

func RunBenchmarks

func RunBenchmarks(benchmarks []Benchmark)

An internal function but exported because it is cross-package; part of the implementation of gotest.

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

func (b *B) ResetTimer()

ResetTimer stops the timer and sets the elapsed benchmark time to zero.

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

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

An internal type but exported because it is cross-package; part of the implementation of gotest.

type Regexp

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

The representation of a compiled regular expression. The public interface is entirely through methods.

func CompileRegexp

func CompileRegexp(str string) (regexp *Regexp, error string)

CompileRegexp parses a regular expression and returns, if successful, a Regexp object that can be used to match against text.

func MustCompile

func MustCompile(str string) *Regexp

MustCompileRegexp is like CompileRegexp but panics if the expression cannot be parsed. It simplifies safe initialization of global variables holding compiled regular expressions.

func (*Regexp) Execute

func (re *Regexp) Execute(b []byte) (a []int)

Execute matches the Regexp against the byte slice b. The return value is an array of integers, in pairs, identifying the positions of subslices matched by the expression.

b[a[0]:a[1]] is the subslice matched by the entire expression.
b[a[2*i]:a[2*i+1]] for i > 0 is the subslice matched by the ith parenthesized subexpression.

A negative value means the subexpression did not match any element of the slice. An empty array means "no match".

func (*Regexp) ExecuteString

func (re *Regexp) ExecuteString(s string) (a []int)

ExecuteString matches the Regexp against the string s. The return value is an array of integers, in pairs, identifying the positions of substrings matched by the expression.

s[a[0]:a[1]] is the substring matched by the entire expression.
s[a[2*i]:a[2*i+1]] for i > 0 is the substring matched by the ith parenthesized subexpression.

A negative value means the subexpression did not match any element of the string. An empty array means "no match".

func (*Regexp) Match

func (re *Regexp) Match(b []byte) bool

Match returns whether the Regexp matches the byte slice b. The return value is a boolean: true for match, false for no match.

func (*Regexp) MatchSlices

func (re *Regexp) MatchSlices(b []byte) (a [][]byte)

MatchSlices matches the Regexp against the byte slice b. The return value is an array of subslices matched by the expression.

a[0] is the subslice matched by the entire expression.
a[i] for i > 0 is the subslice matched by the ith parenthesized subexpression.

An empty array means “no match”.

func (*Regexp) MatchString

func (re *Regexp) MatchString(s string) bool

MatchString returns whether the Regexp matches the string s. The return value is a boolean: true for match, false for no match.

func (*Regexp) MatchStrings

func (re *Regexp) MatchStrings(s string) (a []string)

MatchStrings matches the Regexp against the string s. The return value is an array of strings matched by the expression.

a[0] is the substring matched by the entire expression.
a[i] for i > 0 is the substring matched by the ith parenthesized subexpression.

An empty array means “no match”.

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 (t *T) Error(args ...interface{})

Error is equivalent to Log() followed by Fail().

func (*T) Errorf

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

Errorf is equivalent to Logf() followed by Fail().

func (*T) Fail

func (t *T) Fail()

Fail marks the Test function as having failed but continues execution.

func (*T) FailNow

func (t *T) FailNow()

FailNow marks the Test function as having failed and stops its execution. Execution will continue at the next Test.

func (*T) Failed

func (t *T) Failed() bool

Failed returns whether the Test function has failed.

func (*T) Fatal

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

Fatal is equivalent to Log() followed by FailNow().

func (*T) Fatalf

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

Fatalf is equivalent to Logf() followed by FailNow().

func (*T) Log

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

Log formats its arguments using default formatting, analogous to Print(), and records the text in the error log.

func (*T) Logf

func (t *T) Logf(format string, args ...interface{})

Log formats its arguments according to the format, analogous to Printf(), and records the text in the error log.

type Test

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

An internal type but exported because it is cross-package; part of the implementation of gotest.