Subversion Repositories openrisc

// Copyright 2009 The Go Authors. All rights reserved.

// Use of this source code is governed by a BSD-style

// license that can be found in the LICENSE file.

// Package testing provides support for automated testing of Go packages.

// It is intended to be used in concert with the ``go test'' command, which automates

// execution of any function of the form

//     func TestXxx(*testing.T)

// where Xxx can be any alphanumeric string (but the first letter must not be in

// [a-z]) and serves to identify the test routine.

// These TestXxx routines should be declared within the package they are testing.

//

// Functions of the form

//     func BenchmarkXxx(*testing.B)

// are considered benchmarks, and are executed by gotest when the -test.bench

// flag is provided.

//

// A sample benchmark function looks like this:

//     func BenchmarkHello(b *testing.B) {

//         for i := 0; i < b.N; i++ {

//             fmt.Sprintf("hello")

//         }

//     }

//

// The benchmark package will vary b.N until the benchmark function lasts

// long enough to be timed reliably.  The output

//     testing.BenchmarkHello    10000000    282 ns/op

// means that the loop ran 10000000 times at a speed of 282 ns per loop.

//

// If a benchmark needs some expensive setup before running, the timer

// may be stopped:

//     func BenchmarkBigLen(b *testing.B) {

//         b.StopTimer()

//         big := NewBig()

//         b.StartTimer()

//         for i := 0; i < b.N; i++ {

//             big.Len()

//         }

//     }

//

// The package also runs and verifies example code. Example functions

// include an introductory comment that is compared with the standard output

// of the function when the tests are run, as in this example of an example:

//

//     // hello

//     func ExampleHello() {

//             fmt.Println("hello")

//     }

//

// Example functions without comments are compiled but not executed.

//

// The naming convention to declare examples for a function F, a type T and

// method M on type T are:

//

//     func ExampleF() { ... }

//     func ExampleT() { ... }

//     func ExampleT_M() { ... }

//

// Multiple example functions for a type/function/method may be provided by

// appending a distinct suffix to the name. The suffix must start with a

// lower-case letter.

//

//     func ExampleF_suffix() { ... }

//     func ExampleT_suffix() { ... }

//     func ExampleT_M_suffix() { ... }

//

package testing

import (

        "flag"

        "fmt"

        "os"

        "runtime"

        "runtime/pprof"

        "strconv"

        "strings"

        "time"

)

var (

        // The short flag requests that tests run more quickly, but its functionality

        // is provided by test writers themselves.  The testing package is just its

        // home.  The all.bash installation script sets it to make installation more

        // efficient, but by default the flag is off so a plain "gotest" will do a

        // full test of the package.

        short = flag.Bool("test.short", false, "run smaller test suite to save time")

        // Report as tests are run; default is silent for success.

        chatty         = flag.Bool("test.v", false, "verbose: print additional output")

        match          = flag.String("test.run", "", "regular expression to select tests to run")

        memProfile     = flag.String("test.memprofile", "", "write a memory profile to the named file after execution")

        memProfileRate = flag.Int("test.memprofilerate", 0, "if >=0, sets runtime.MemProfileRate")

        cpuProfile     = flag.String("test.cpuprofile", "", "write a cpu profile to the named file during execution")

        timeout        = flag.Duration("test.timeout", 0, "if positive, sets an aggregate time limit for all tests")

        cpuListStr     = flag.String("test.cpu", "", "comma-separated list of number of CPUs to use for each test")

        parallel       = flag.Int("test.parallel", runtime.GOMAXPROCS(0), "maximum test parallelism")

        cpuList []int

)

// common holds the elements common between T and B and

// captures common methods such as Errorf.

type common struct {

        output   []byte    // Output generated by test or benchmark.

        failed   bool      // Test or benchmark has failed.

        start    time.Time // Time test or benchmark started

        duration time.Duration

        self     interface{}      // To be sent on signal channel when done.

        signal   chan interface{} // Output for serial tests.

}

// Short reports whether the -test.short flag is set.

func Short() bool {

        return *short

}

// decorate inserts the final newline if needed and indentation tabs for formatting.

// If addFileLine is true, it also prefixes the string with the file and line of the call site.

func decorate(s string, addFileLine bool) string {

        if addFileLine {

                _, file, line, ok := runtime.Caller(3) // decorate + log + public function.

                if ok {

                        // Truncate file name at last file name separator.

                        if index := strings.LastIndex(file, "/"); index >= 0 {

                                file = file[index+1:]

                        } else if index = strings.LastIndex(file, "\\"); index >= 0 {

                                file = file[index+1:]

                        }

                } else {

                        file = "???"

                        line = 1

                }

                s = fmt.Sprintf("%s:%d: %s", file, line, s)

        }

        s = "\t" + s // Every line is indented at least one tab.

        n := len(s)

        if n > 0 && s[n-1] != '\n' {

                s += "\n"

                n++

        }

        for i := 0; i < n-1; i++ { // -1 to avoid final newline

                if s[i] == '\n' {

                        // Second and subsequent lines are indented an extra tab.

                        return s[0:i+1] + "\t" + decorate(s[i+1:n], false)

                }

        }

        return s

}

// T is a type passed to Test functions to manage test state and support formatted test logs.

// Logs are accumulated during execution and dumped to standard error when done.

type T struct {

        common

        name          string    // Name of test.

        startParallel chan bool // Parallel tests will wait on this.

}

// Fail marks the function as having failed but continues execution.

func (c *common) Fail() { c.failed = true }

// Failed returns whether the function has failed.

func (c *common) Failed() bool { return c.failed }

// FailNow marks the function as having failed and stops its execution.

// Execution will continue at the next Test.

func (c *common) FailNow() {

        c.Fail()

        // Calling runtime.Goexit will exit the goroutine, which

        // will run the deferred functions in this goroutine,

        // which will eventually run the deferred lines in tRunner,

        // which will signal to the test loop that this test is done.

        //

        // A previous version of this code said:

        //

        //      c.duration = ...

        //      c.signal <- c.self

        //      runtime.Goexit()

        //

        // This previous version duplicated code (those lines are in

        // tRunner no matter what), but worse the goroutine teardown

        // implicit in runtime.Goexit was not guaranteed to complete

        // before the test exited.  If a test deferred an important cleanup

        // function (like removing temporary files), there was no guarantee

        // it would run on a test failure.  Because we send on c.signal during

        // a top-of-stack deferred function now, we know that the send

        // only happens after any other stacked defers have completed.

        runtime.Goexit()

}

// log generates the output. It's always at the same stack depth.

func (c *common) log(s string) {

        c.output = append(c.output, decorate(s, true)...)

}

// Log formats its arguments using default formatting, analogous to Println(),

// and records the text in the error log.

func (c *common) Log(args ...interface{}) { c.log(fmt.Sprintln(args...)) }

// Logf formats its arguments according to the format, analogous to Printf(),

// and records the text in the error log.

func (c *common) Logf(format string, args ...interface{}) { c.log(fmt.Sprintf(format, args...)) }

// Error is equivalent to Log() followed by Fail().

func (c *common) Error(args ...interface{}) {

        c.log(fmt.Sprintln(args...))

        c.Fail()

}

// Errorf is equivalent to Logf() followed by Fail().

func (c *common) Errorf(format string, args ...interface{}) {

        c.log(fmt.Sprintf(format, args...))

        c.Fail()

}

// Fatal is equivalent to Log() followed by FailNow().

func (c *common) Fatal(args ...interface{}) {

        c.log(fmt.Sprintln(args...))

        c.FailNow()

}

// Fatalf is equivalent to Logf() followed by FailNow().

func (c *common) Fatalf(format string, args ...interface{}) {

        c.log(fmt.Sprintf(format, args...))

        c.FailNow()

}

// TODO(dsymonds): Consider hooking into runtime·traceback instead.

func (c *common) stack() {

        for i := 2; ; i++ { // Caller we care about is the user, 2 frames up

                pc, file, line, ok := runtime.Caller(i)

                f := runtime.FuncForPC(pc)

                if !ok || f == nil {

                        break

                }

                c.Logf("%s:%d (0x%x)", file, line, pc)

                c.Logf("\t%s", f.Name())

        }

}

// Parallel signals that this test is to be run in parallel with (and only with)

// other parallel tests in this CPU group.

func (t *T) Parallel() {

        t.signal <- (*T)(nil) // Release main testing loop

        <-t.startParallel     // Wait for serial tests to finish

}

// An internal type but exported because it is cross-package; part of the implementation

// of gotest.

type InternalTest struct {

        Name string

        F    func(*T)

}

func tRunner(t *T, test *InternalTest) {

        t.start = time.Now()

        // When this goroutine is done, either because test.F(t)

        // returned normally or because a test failure triggered

        // a call to runtime.Goexit, record the duration and send

        // a signal saying that the test is done.

        defer func() {

                // Consider any uncaught panic a failure.

                if err := recover(); err != nil {

                        t.failed = true

                        t.Log(err)

                        t.stack()

                }

                t.duration = time.Now().Sub(t.start)

                t.signal <- t

        }()

        test.F(t)

}

// An internal function but exported because it is cross-package; part of the implementation

// of gotest.

func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) {

        flag.Parse()

        parseCpuList()

        before()

        startAlarm()

        testOk := RunTests(matchString, tests)

        exampleOk := RunExamples(examples)

        if !testOk || !exampleOk {

                fmt.Println("FAIL")

                os.Exit(1)

        }

        fmt.Println("PASS")

        stopAlarm()

        RunBenchmarks(matchString, benchmarks)

        after()

}

func (t *T) report() {

        tstr := fmt.Sprintf("(%.2f seconds)", t.duration.Seconds())

        format := "--- %s: %s %s\n%s"

        if t.failed {

                fmt.Printf(format, "FAIL", t.name, tstr, t.output)

        } else if *chatty {

                fmt.Printf(format, "PASS", t.name, tstr, t.output)

        }

}

func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool) {

        ok = true

        if len(tests) == 0 {

                fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")

                return

        }

        for _, procs := range cpuList {

                runtime.GOMAXPROCS(procs)

                // We build a new channel tree for each run of the loop.

                // collector merges in one channel all the upstream signals from parallel tests.

                // If all tests pump to the same channel, a bug can occur where a test

                // kicks off a goroutine that Fails, yet the test still delivers a completion signal,

                // which skews the counting.

                var collector = make(chan interface{})

                numParallel := 0

                startParallel := make(chan bool)

                for i := 0; i < len(tests); i++ {

                        matched, err := matchString(*match, tests[i].Name)

                        if err != nil {

                                fmt.Fprintf(os.Stderr, "testing: invalid regexp for -test.run: %s\n", err)

                                os.Exit(1)

                        }

                        if !matched {

                                continue

                        }

                        testName := tests[i].Name

                        if procs != 1 {

                                testName = fmt.Sprintf("%s-%d", tests[i].Name, procs)

                        }

                        t := &T{

                                common: common{

                                        signal: make(chan interface{}),

                                },

                                name:          testName,

                                startParallel: startParallel,

                        }

                        t.self = t

                        if *chatty {

                                fmt.Printf("=== RUN %s\n", t.name)

                        }

                        go tRunner(t, &tests[i])

                        out := (<-t.signal).(*T)

                        if out == nil { // Parallel run.

                                go func() {

                                        collector <- <-t.signal

                                }()

                                numParallel++

                                continue

                        }

                        t.report()

                        ok = ok && !out.failed

                }

                running := 0

                for numParallel+running > 0 {

                        if running < *parallel && numParallel > 0 {

                                startParallel <- true

                                running++

                                numParallel--

                                continue

                        }

                        t := (<-collector).(*T)

                        t.report()

                        ok = ok && !t.failed

                        running--

                }

        }

        return

}

// before runs before all testing.

func before() {

        if *memProfileRate > 0 {

                runtime.MemProfileRate = *memProfileRate

        }

        if *cpuProfile != "" {

                f, err := os.Create(*cpuProfile)

                if err != nil {

                        fmt.Fprintf(os.Stderr, "testing: %s", err)

                        return

                }

                if err := pprof.StartCPUProfile(f); err != nil {

                        fmt.Fprintf(os.Stderr, "testing: can't start cpu profile: %s", err)

                        f.Close()

                        return

                }

                // Could save f so after can call f.Close; not worth the effort.

        }

}

// after runs after all testing.

func after() {

        if *cpuProfile != "" {

                pprof.StopCPUProfile() // flushes profile to disk

        }

        if *memProfile != "" {

                f, err := os.Create(*memProfile)

                if err != nil {

                        fmt.Fprintf(os.Stderr, "testing: %s", err)

                        return

                }

                if err = pprof.WriteHeapProfile(f); err != nil {

                        fmt.Fprintf(os.Stderr, "testing: can't write %s: %s", *memProfile, err)

                }

                f.Close()

        }

}

var timer *time.Timer

// startAlarm starts an alarm if requested.

func startAlarm() {

        if *timeout > 0 {

                timer = time.AfterFunc(*timeout, alarm)

        }

}

// stopAlarm turns off the alarm.

func stopAlarm() {

        if *timeout > 0 {

                timer.Stop()

        }

}

// alarm is called if the timeout expires.

func alarm() {

        panic("test timed out")

}

func parseCpuList() {

        if len(*cpuListStr) == 0 {

                cpuList = append(cpuList, runtime.GOMAXPROCS(-1))

        } else {

                for _, val := range strings.Split(*cpuListStr, ",") {

                        cpu, err := strconv.Atoi(val)

                        if err != nil || cpu <= 0 {

                                fmt.Fprintf(os.Stderr, "testing: invalid value %q for -test.cpu", val)

                                os.Exit(1)

                        }

                        cpuList = append(cpuList, cpu)

                }

        }

}