libgo/go/go/doc/testdata/testing.1.golden

   1 // Package testing provides support for automated testing of Go ...
   2 PACKAGE testing
   3
   4 IMPORTPATH
   5         testdata/testing
   6
   7 IMPORTS
   8         bytes
   9         flag
  10         fmt
  11         io
  12         os
  13         runtime
  14         runtime/pprof
  15         strconv
  16         strings
  17         time
  18
  19 FILENAMES
  20         testdata/benchmark.go
  21         testdata/example.go
  22         testdata/testing.go
  23
  24 VARIABLES
  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
  57 FUNCTIONS
  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
 110 TYPES
 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