...
Run Format

Package testing

Overview ▾

testingパッケージはGoのパッケージの自動テストを支援します。 これは“go test”コマンドとともに使用することで、次のような形式の関数を自動実行します。

func TestXxx(*testing.T)

Xxxはどんな英数字の文字列でもよく(ただし、最初の文字は[a-z]以外でなければなりません)、テストルーチンを識別するために用いられれます。

これらの関数内では、ErrorやFailといったメソッドを使用することで、失敗を報告することができます。

新しいテストスイートを書くには、名前が_test.goで終わり、ここで説明したTestXxx関数を含むファイルを作成してください。 ファイルは、テストされるものと同一のパッケージに配置してください。 このファイルは通常のパッケージビルドからは除外されますが、“go test”コマンドで実行されるときには含まれます。 詳細については、“go help test”や“go help testflag”を実行してみてください。

テストとベンチマークは、実行したくない状況では*Tや*BのSkipメソッドを呼び出すことでスキップできます:

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

Benchmarks

次のような形式の関数

func BenchmarkXxx(*testing.B)

は、ベンチマークとみなされ、"go test"コマンドに-benchフラグが与えられたときに実行されます。 ベンチマークは順次実行されます。

テストフラグの詳細については、こちらを参照してください: http://golang-jp.org/pkg/cmd/go/#hdr-Go__________________

サンプルのベンチマーク関数は次のようになります:

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

ベンチマーク関数は対象のコードをb.N回実行しなければなりません。 testingパッケージは、ベンチマーク関数が十分な時間継続するようになるまでb.Nを変化させます。 出力の

BenchmarkHello    10000000    282 ns/op

は、ループが10000000回、一回あたり282ナノ秒で実行されたことを意味します。

もしベンチマークで処理がはじまる前に時間のかかる初期化が必要なら、タイマーをリセットすることもできます:

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

もしベンチマークで並列処理の性能をテストする必要があれば、RunParallelヘルパー関数を使うこともできます; このようなベンチマークはgo test -cpuフラグと一緒に使用できます:

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

testingパッケージは用例となるコード(Example関数)を実行し、検証します。 Example関数は結果について"Output:"で始まる一行コメントを含むことができ、テストが実行された際の関数の標準出力と比較されます。 (比較の際、前後の空白は無視されます。) Example関数の例を示します:

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

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

Example関数で"Output:"のコメントがないものは、コンパイルはされますが実行はされません。

Example関数には命名規則があり、そのパッケージ内の関数F、型T、型TのメソッドMの用例を書くには次のようにします:

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

複数のExample関数を一つのパッケージ/型/関数/メソッドについて書くには、固有のサフィックスを名前に追加してください。 サフィックスは、小文字で始まる必要があります。

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

テストファイルが一つのExample関数だけを含む場合、ファイル全体が用例として提示されます。 これは他の関数や型、変数、定数の宣言を少なくとも一つ含み、テスト関数やベンチマーク関数を含まない必要があります。

Main

時には、テストの前後で追加の初期化や終了処理がテストプログラムで必要になることもあります。 また、メインスレッドで実行されるように制御する必要があるテストもあります。 これらをサポートするために、もしテストファイルが次の関数を含んでいた場合には:

func TestMain(m *testing.M)

生成されたテストはテストを直接実行する代わりに、TestMain(m)を呼び出します。 TestMainはメインのゴルーチンで実行されるため、m.Runの呼び出しの前後で必要な初期化や終了処理を挟むことができます。 ここではm.Runの結果をもとにos.Exitを呼び出すべきです。

TestMainの最小実装は:

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

実際のところ、この実装はTestMainが明示的に定義されなかった場合に使用されます。

本ドキュメントは以下のドキュメントを翻訳しています: https://code.google.com/p/go/source/browse/src/testing/testing.go?r=804cc55d6b47e49e4bf46baa4ca9ec44b9684bed

func AllocsPerRun

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 Coverage

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 RegisterCover

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

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)

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) 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 zeros the elapsed benchmark time and memory allocation counters. It does not affect whether the timer is running.

func (*B) RunParallel

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.

Example

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

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 (*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 Cover

type Cover struct {
    Mode            string
    Counters        map[string][]uint32
    Blocks          map[string][]CoverBlock
    CoveredPackages string
}

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 CoverBlock

type CoverBlock struct {
    Line0 uint32
    Col0  uint16
    Line1 uint32
    Col1  uint16
    Stmts uint16
}

CoverBlock records the coverage data for a single basic block. NOTE: This struct is internal to the testing infrastructure and may change. It is not covered (yet) by the Go 1 compatibility guidelines.

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 PB

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

A PB is used by RunParallel for running parallel benchmarks.

func (*PB) Next

func (pb *PB) Next() bool

Next reports whether there are more iterations to execute.

Subdirectories

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