libgo/go/testing/testing.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 // The testing package provides support for automated testing of Go packages.
   6 // It is intended to be used in concert with the ``gotest'' utility, which automates
   7 // execution of any function of the form
   8 //     func TestXxx(*testing.T)
   9 // where Xxx can be any alphanumeric string (but the first letter must not be in
  10 // [a-z]) and serves to identify the test routine.
  11 // These TestXxx routines should be declared within the package they are testing.
  12 //
  13 // Functions of the form
  14 //     func BenchmarkXxx(*testing.B)
  15 // are considered benchmarks, and are executed by gotest when the -test.bench
  16 // flag is provided.
  17 //
  18 // A sample benchmark function looks like this:
  19 //     func BenchmarkHello(b *testing.B) {
  20 //         for i := 0; i < b.N; i++ {
  21 //             fmt.Sprintf("hello")
  22 //         }
  23 //     }
  24 // The benchmark package will vary b.N until the benchmark function lasts
  25 // long enough to be timed reliably.  The output
  26 //     testing.BenchmarkHello   500000        4076 ns/op
  27 // means that the loop ran 500000 times at a speed of 4076 ns per loop.
  28 //
  29 // If a benchmark needs some expensive setup before running, the timer
  30 // may be stopped:
  31 //     func BenchmarkBigLen(b *testing.B) {
  32 //         b.StopTimer()
  33 //         big := NewBig()
  34 //         b.StartTimer()
  35 //         for i := 0; i < b.N; i++ {
  36 //             big.Len()
  37 //         }
  38 //     }
  39 package testing
  40
  41 import (
  42         "flag"
  43         "fmt"
  44         "os"
  45         "runtime"
  46         "runtime/pprof"
  47         "time"
  48 )
  49
  50 var (
  51         // The short flag requests that tests run more quickly, but its functionality
  52         // is provided by test writers themselves.  The testing package is just its
  53         // home.  The all.bash installation script sets it to make installation more
  54         // efficient, but by default the flag is off so a plain "gotest" will do a
  55         // full test of the package.
  56         short = flag.Bool("test.short", false, "run smaller test suite to save time")
  57
  58         // Report as tests are run; default is silent for success.
  59         chatty         = flag.Bool("test.v", false, "verbose: print additional output")
  60         match          = flag.String("test.run", "", "regular expression to select tests to run")
  61         memProfile     = flag.String("test.memprofile", "", "write a memory profile to the named file after execution")
  62         memProfileRate = flag.Int("test.memprofilerate", 0, "if >=0, sets runtime.MemProfileRate")
  63         cpuProfile     = flag.String("test.cpuprofile", "", "write a cpu profile to the named file during execution")
  64 )
  65
  66 // Short reports whether the -test.short flag is set.
  67 func Short() bool {
  68         return *short
  69 }
  70
  71
  72 // Insert final newline if needed and tabs after internal newlines.
  73 func tabify(s string) string {
  74         n := len(s)
  75         if n > 0 && s[n-1] != '\n' {
  76                 s += "\n"
  77                 n++
  78         }
  79         for i := 0; i < n-1; i++ { // -1 to avoid final newline
  80                 if s[i] == '\n' {
  81                         return s[0:i+1] + "\t" + tabify(s[i+1:n])
  82                 }
  83         }
  84         return s
  85 }
  86
  87 // T is a type passed to Test functions to manage test state and support formatted test logs.
  88 // Logs are accumulated during execution and dumped to standard error when done.
  89 type T struct {
  90         errors string
  91         failed bool
  92         ch     chan *T
  93 }
  94
  95 // Fail marks the Test function as having failed but continues execution.
  96 func (t *T) Fail() { t.failed = true }
  97
  98 // Failed returns whether the Test function has failed.
  99 func (t *T) Failed() bool { return t.failed }
 100
 101 // FailNow marks the Test function as having failed and stops its execution.
 102 // Execution will continue at the next Test.
 103 func (t *T) FailNow() {
 104         t.Fail()
 105         t.ch <- t
 106         runtime.Goexit()
 107 }
 108
 109 // Log formats its arguments using default formatting, analogous to Print(),
 110 // and records the text in the error log.
 111 func (t *T) Log(args ...interface{}) { t.errors += "\t" + tabify(fmt.Sprintln(args...)) }
 112
 113 // Logf formats its arguments according to the format, analogous to Printf(),
 114 // and records the text in the error log.
 115 func (t *T) Logf(format string, args ...interface{}) {
 116         t.errors += "\t" + tabify(fmt.Sprintf(format, args...))
 117 }
 118
 119 // Error is equivalent to Log() followed by Fail().
 120 func (t *T) Error(args ...interface{}) {
 121         t.Log(args...)
 122         t.Fail()
 123 }
 124
 125 // Errorf is equivalent to Logf() followed by Fail().
 126 func (t *T) Errorf(format string, args ...interface{}) {
 127         t.Logf(format, args...)
 128         t.Fail()
 129 }
 130
 131 // Fatal is equivalent to Log() followed by FailNow().
 132 func (t *T) Fatal(args ...interface{}) {
 133         t.Log(args...)
 134         t.FailNow()
 135 }
 136
 137 // Fatalf is equivalent to Logf() followed by FailNow().
 138 func (t *T) Fatalf(format string, args ...interface{}) {
 139         t.Logf(format, args...)
 140         t.FailNow()
 141 }
 142
 143 // An internal type but exported because it is cross-package; part of the implementation
 144 // of gotest.
 145 type InternalTest struct {
 146         Name string
 147         F    func(*T)
 148 }
 149
 150 func tRunner(t *T, test *InternalTest) {
 151         test.F(t)
 152         t.ch <- t
 153 }
 154
 155 // An internal function but exported because it is cross-package; part of the implementation
 156 // of gotest.
 157 func Main(matchString func(pat, str string) (bool, os.Error), tests []InternalTest, benchmarks []InternalBenchmark) {
 158         flag.Parse()
 159
 160         before()
 161         RunTests(matchString, tests)
 162         RunBenchmarks(matchString, benchmarks)
 163         after()
 164 }
 165
 166 func RunTests(matchString func(pat, str string) (bool, os.Error), tests []InternalTest) {
 167         ok := true
 168         if len(tests) == 0 {
 169                 println("testing: warning: no tests to run")
 170         }
 171         for i := 0; i < len(tests); i++ {
 172                 matched, err := matchString(*match, tests[i].Name)
 173                 if err != nil {
 174                         println("invalid regexp for -test.run:", err.String())
 175                         os.Exit(1)
 176                 }
 177                 if !matched {
 178                         continue
 179                 }
 180                 if *chatty {
 181                         println("=== RUN ", tests[i].Name)
 182                 }
 183                 ns := -time.Nanoseconds()
 184                 t := new(T)
 185                 t.ch = make(chan *T)
 186                 go tRunner(t, &tests[i])
 187                 <-t.ch
 188                 ns += time.Nanoseconds()
 189                 tstr := fmt.Sprintf("(%.2f seconds)", float64(ns)/1e9)
 190                 if t.failed {
 191                         println("--- FAIL:", tests[i].Name, tstr)
 192                         print(t.errors)
 193                         ok = false
 194                 } else if *chatty {
 195                         println("--- PASS:", tests[i].Name, tstr)
 196                         print(t.errors)
 197                 }
 198         }
 199         if !ok {
 200                 println("FAIL")
 201                 os.Exit(1)
 202         }
 203         println("PASS")
 204 }
 205
 206 // before runs before all testing.
 207 func before() {
 208         if *memProfileRate > 0 {
 209                 runtime.MemProfileRate = *memProfileRate
 210         }
 211         if *cpuProfile != "" {
 212                 f, err := os.Open(*cpuProfile, os.O_WRONLY|os.O_CREAT|os.O_TRUNC, 0666)
 213                 if err != nil {
 214                         fmt.Fprintf(os.Stderr, "testing: %s", err)
 215                         return
 216                 }
 217                 if err := pprof.StartCPUProfile(f); err != nil {
 218                         fmt.Fprintf(os.Stderr, "testing: can't start cpu profile: %s", err)
 219                         f.Close()
 220                         return
 221                 }
 222                 // Could save f so after can call f.Close; not worth the effort.
 223         }
 224
 225 }
 226
 227 // after runs after all testing.
 228 func after() {
 229         if *cpuProfile != "" {
 230                 pprof.StopCPUProfile() // flushes profile to disk
 231         }
 232         if *memProfile != "" {
 233                 f, err := os.Open(*memProfile, os.O_WRONLY|os.O_CREAT|os.O_TRUNC, 0666)
 234                 if err != nil {
 235                         fmt.Fprintf(os.Stderr, "testing: %s", err)
 236                         return
 237                 }
 238                 if err = pprof.WriteHeapProfile(f); err != nil {
 239                         fmt.Fprintf(os.Stderr, "testing: can't write %s: %s", *memProfile, err)
 240                 }
 241                 f.Close()
 242         }
 243 }