Source file src/cmd/gotest/doc.go
1 // Copyright 2009 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 /* 6 7 Gotest is an automated testing tool for Go packages. 8 9 Normally a Go package is compiled without its test files. Gotest is a 10 tool that recompiles the package whose source is in the current 11 directory, along with any files whose names match the pattern 12 "[^.]*_test.go". Functions in the test source named TestXXX (where 13 XXX is any alphanumeric string not starting with a lower case letter) 14 will be run when the binary is executed. Gotest requires that the 15 package have a standard package Makefile, one that includes 16 go/src/Make.pkg. 17 18 The test functions are run in the order they appear in the source. 19 They should have the signature, 20 21 func TestXXX(t *testing.T) { ... } 22 23 Benchmark functions can be written as well; they will be run only when 24 the -test.bench flag is provided. Benchmarks should have the 25 signature, 26 27 func BenchmarkXXX(b *testing.B) { ... } 28 29 See the documentation of the testing package for more information. 30 31 By default, gotest needs no arguments. It compiles all the .go files 32 in the directory, including tests, and runs the tests. If file names 33 are given (with flag -file=test.go, one per extra test source file), 34 only those test files are added to the package. (The non-test files 35 are always compiled.) 36 37 The package is built in a special subdirectory so it does not 38 interfere with the non-test installation. 39 40 Usage: 41 gotest [-file a.go -file b.go ...] [-c] [-x] [args for test binary] 42 43 The flags specific to gotest are: 44 -c Compile the test binary but do not run it. 45 -file a.go Use only the tests in the source file a.go. 46 Multiple -file flags may be provided. 47 -x Print each subcommand gotest executes. 48 49 Everything else on the command line is passed to the test binary. 50 51 The resulting test binary, called (for amd64) 6.out, has several flags. 52 53 Usage: 54 6.out [-test.v] [-test.run pattern] [-test.bench pattern] \ 55 [-test.cpuprofile=cpu.out] \ 56 [-test.memprofile=mem.out] [-test.memprofilerate=1] \ 57 [-test.timeout=10] [-test.short] \ 58 [-test.benchtime=3] [-test.cpu=1,2,3,4] 59 60 The -test.v flag causes the tests to be logged as they run. The 61 -test.run flag causes only those tests whose names match the regular 62 expression pattern to be run. By default all tests are run silently. 63 64 If all specified tests pass, 6.out prints the word PASS and exits with 65 a 0 exit code. If any tests fail, it prints error details, the word 66 FAIL, and exits with a non-zero code. The -test.bench flag is 67 analogous to the -test.run flag, but applies to benchmarks. No 68 benchmarks run by default. 69 70 The -test.cpuprofile flag causes the testing software to write a CPU 71 profile to the specified file before exiting. 72 73 The -test.memprofile flag causes the testing software to write a 74 memory profile to the specified file when all tests are complete. The 75 -test.memprofilerate flag enables more precise (and expensive) 76 profiles by setting runtime.MemProfileRate; run 77 godoc runtime MemProfileRate 78 for details. The defaults are no memory profile and the standard 79 setting of MemProfileRate. The memory profile records a sampling of 80 the memory in use at the end of the test. To profile all memory 81 allocations, use -test.memprofilerate=1 to sample every byte and set 82 the environment variable GOGC=off to disable the garbage collector, 83 provided the test can run in the available memory without garbage 84 collection. 85 86 Use -test.run or -test.bench to limit profiling to a particular test 87 or benchmark. 88 89 The -test.short flag tells long-running tests to shorten their run 90 time. It is off by default but set by all.bash so installations of 91 the Go tree can do a sanity check but not spend time running 92 exhaustive tests. 93 94 The -test.timeout flag sets a timeout for the test in seconds. If the 95 test runs for longer than that, it will panic, dumping a stack trace 96 of all existing goroutines. 97 98 The -test.benchtime flag specifies the number of seconds to run each benchmark. 99 The default is one second. 100 101 The -test.cpu flag specifies a list of GOMAXPROCS values for which 102 the tests or benchmarks are executed. The default is the current 103 value of GOMAXPROCS. 104 105 For convenience, each of these -test.X flags of the test binary is 106 also available as the flag -X in gotest itself. Flags not listed here 107 are unaffected. For instance, the command 108 gotest -x -v -cpuprofile=prof.out -dir=testdata -update -file x_test.go 109 will compile the test binary using x_test.go and then run it as 110 6.out -test.v -test.cpuprofile=prof.out -dir=testdata -update 111 112 */ 113 package documentation