1// Package testing provides support for automated testing of Go ... 2PACKAGE testing 3 4IMPORTPATH 5 testdata/testing 6 7IMPORTS 8 bytes 9 flag 10 fmt 11 io 12 os 13 runtime 14 runtime/pprof 15 strconv 16 strings 17 time 18 19FILENAMES 20 testdata/benchmark.go 21 testdata/example.go 22 testdata/testing.go 23 24VARIABLES 25 // 26 var ( 27 // The short flag requests that tests run more quickly, but its functionality 28 // is provided by test writers themselves. The testing package is just its 29 // home. The all.bash installation script sets it to make installation more 30 // efficient, but by default the flag is off so a plain "go test" will do a 31 // full test of the package. 32 short = flag.Bool("test.short", false, "run smaller test suite to save time") 33 34 // Report as tests are run; default is silent for success. 35 chatty = flag.Bool("test.v", false, "verbose: print additional output") 36 match = flag.String("test.run", "", "regular expression to select tests to run") 37 memProfile = flag.String("test.memprofile", "", "write a memory profile to the named file after execution") 38 memProfileRate = flag.Int("test.memprofilerate", 0, "if >=0, sets runtime.MemProfileRate") 39 cpuProfile = flag.String("test.cpuprofile", "", "write a cpu profile to the named file during execution") 40 timeout = flag.Duration("test.timeout", 0, "if positive, sets an aggregate time limit for all tests") 41 cpuListStr = flag.String("test.cpu", "", "comma-separated list of number of CPUs to use for each test") 42 parallel = flag.Int("test.parallel", runtime.GOMAXPROCS(0), "maximum test parallelism") 43 44 cpuList []int 45 ) 46 47 // 48 var benchTime = flag.Duration("test.benchtime", 1*time.Second, "approximate run time for each benchmark") 49 50 // 51 var matchBenchmarks = flag.String("test.bench", "", "regular expression to select benchmarks to run") 52 53 // 54 var timer *time.Timer 55 56 57FUNCTIONS 58 // An internal function but exported because it is cross-package; ... 59 func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) 60 61 // An internal function but exported because it is cross-package; ... 62 func RunBenchmarks(matchString func(pat, str string) (bool, error), benchmarks []InternalBenchmark) 63 64 // 65 func RunExamples(examples []InternalExample) (ok bool) 66 67 // 68 func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool) 69 70 // Short reports whether the -test.short flag is set. 71 func Short() bool 72 73 // after runs after all testing. 74 func after() 75 76 // alarm is called if the timeout expires. 77 func alarm() 78 79 // before runs before all testing. 80 func before() 81 82 // decorate inserts the final newline if needed and indentation ... 83 func decorate(s string, addFileLine bool) string 84 85 // 86 func max(x, y int) int 87 88 // 89 func min(x, y int) int 90 91 // 92 func parseCpuList() 93 94 // roundDown10 rounds a number down to the nearest power of 10. 95 func roundDown10(n int) int 96 97 // roundUp rounds x up to a number of the form [1eX, 2eX, 5eX]. 98 func roundUp(n int) int 99 100 // startAlarm starts an alarm if requested. 101 func startAlarm() 102 103 // stopAlarm turns off the alarm. 104 func stopAlarm() 105 106 // 107 func tRunner(t *T, test *InternalTest) 108 109 110TYPES 111 // B is a type passed to Benchmark functions to manage benchmark ... 112 type B struct { 113 common 114 N int 115 benchmark InternalBenchmark 116 bytes int64 117 timerOn bool 118 result BenchmarkResult 119 } 120 121 // Error is equivalent to Log() followed by Fail(). 122 func (c *B) Error(args ...interface{}) 123 124 // Errorf is equivalent to Logf() followed by Fail(). 125 func (c *B) Errorf(format string, args ...interface{}) 126 127 // Fail marks the function as having failed but continues ... 128 func (c *B) Fail() 129 130 // FailNow marks the function as having failed and stops its ... 131 func (c *B) FailNow() 132 133 // Failed reports whether the function has failed. 134 func (c *B) Failed() bool 135 136 // Fatal is equivalent to Log() followed by FailNow(). 137 func (c *B) Fatal(args ...interface{}) 138 139 // Fatalf is equivalent to Logf() followed by FailNow(). 140 func (c *B) Fatalf(format string, args ...interface{}) 141 142 // Log formats its arguments using default formatting, analogous ... 143 func (c *B) Log(args ...interface{}) 144 145 // Logf formats its arguments according to the format, analogous ... 146 func (c *B) Logf(format string, args ...interface{}) 147 148 // ResetTimer sets the elapsed benchmark time to zero. It does not ... 149 func (b *B) ResetTimer() 150 151 // SetBytes records the number of bytes processed in a single ... 152 func (b *B) SetBytes(n int64) 153 154 // StartTimer starts timing a test. This function is called ... 155 func (b *B) StartTimer() 156 157 // StopTimer stops timing a test. This can be used to pause the ... 158 func (b *B) StopTimer() 159 160 // launch launches the benchmark function. It gradually increases ... 161 func (b *B) launch() 162 163 // log generates the output. It's always at the same stack depth. 164 func (c *B) log(s string) 165 166 // 167 func (b *B) nsPerOp() int64 168 169 // run times the benchmark function in a separate goroutine. 170 func (b *B) run() BenchmarkResult 171 172 // runN runs a single benchmark for the specified number of ... 173 func (b *B) runN(n int) 174 175 // trimOutput shortens the output from a benchmark, which can be ... 176 func (b *B) trimOutput() 177 178 // The results of a benchmark run. 179 type BenchmarkResult struct { 180 N int // The number of iterations. 181 T time.Duration // The total time taken. 182 Bytes int64 // Bytes processed in one iteration. 183 } 184 185 // Benchmark benchmarks a single function. Useful for creating ... 186 func Benchmark(f func(b *B)) BenchmarkResult 187 188 // 189 func (r BenchmarkResult) NsPerOp() int64 190 191 // 192 func (r BenchmarkResult) String() string 193 194 // 195 func (r BenchmarkResult) mbPerSec() float64 196 197 // An internal type but exported because it is cross-package; part ... 198 type InternalBenchmark struct { 199 Name string 200 F func(b *B) 201 } 202 203 // 204 type InternalExample struct { 205 Name string 206 F func() 207 Output string 208 } 209 210 // An internal type but exported because it is cross-package; part ... 211 type InternalTest struct { 212 Name string 213 F func(*T) 214 } 215 216 // T is a type passed to Test functions to manage test state and ... 217 type T struct { 218 common 219 name string // Name of test. 220 startParallel chan bool // Parallel tests will wait on this. 221 } 222 223 // Error is equivalent to Log() followed by Fail(). 224 func (c *T) Error(args ...interface{}) 225 226 // Errorf is equivalent to Logf() followed by Fail(). 227 func (c *T) Errorf(format string, args ...interface{}) 228 229 // Fail marks the function as having failed but continues ... 230 func (c *T) Fail() 231 232 // FailNow marks the function as having failed and stops its ... 233 func (c *T) FailNow() 234 235 // Failed reports whether the function has failed. 236 func (c *T) Failed() bool 237 238 // Fatal is equivalent to Log() followed by FailNow(). 239 func (c *T) Fatal(args ...interface{}) 240 241 // Fatalf is equivalent to Logf() followed by FailNow(). 242 func (c *T) Fatalf(format string, args ...interface{}) 243 244 // Log formats its arguments using default formatting, analogous ... 245 func (c *T) Log(args ...interface{}) 246 247 // Logf formats its arguments according to the format, analogous ... 248 func (c *T) Logf(format string, args ...interface{}) 249 250 // Parallel signals that this test is to be run in parallel with ... 251 func (t *T) Parallel() 252 253 // log generates the output. It's always at the same stack depth. 254 func (c *T) log(s string) 255 256 // 257 func (t *T) report() 258 259 // common holds the elements common between T and B and captures ... 260 type common struct { 261 output []byte // Output generated by test or benchmark. 262 failed bool // Test or benchmark has failed. 263 start time.Time // Time test or benchmark started 264 duration time.Duration 265 self interface{} // To be sent on signal channel when done. 266 signal chan interface{} // Output for serial tests. 267 } 268 269 // Error is equivalent to Log() followed by Fail(). 270 func (c *common) Error(args ...interface{}) 271 272 // Errorf is equivalent to Logf() followed by Fail(). 273 func (c *common) Errorf(format string, args ...interface{}) 274 275 // Fail marks the function as having failed but continues ... 276 func (c *common) Fail() 277 278 // FailNow marks the function as having failed and stops its ... 279 func (c *common) FailNow() 280 281 // Failed reports whether the function has failed. 282 func (c *common) Failed() bool 283 284 // Fatal is equivalent to Log() followed by FailNow(). 285 func (c *common) Fatal(args ...interface{}) 286 287 // Fatalf is equivalent to Logf() followed by FailNow(). 288 func (c *common) Fatalf(format string, args ...interface{}) 289 290 // Log formats its arguments using default formatting, analogous ... 291 func (c *common) Log(args ...interface{}) 292 293 // Logf formats its arguments according to the format, analogous ... 294 func (c *common) Logf(format string, args ...interface{}) 295 296 // log generates the output. It's always at the same stack depth. 297 func (c *common) log(s string) 298 299