From: Russ Cox Date: Mon, 4 Feb 2013 04:47:03 +0000 (-0500) Subject: cmd/go, testing: revise docs for test flags X-Git-Tag: go1.1rc2~1153 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=89a2a8c8df6f494dc75dd6a44dcd8ad1eccf1a20;p=gostls13.git cmd/go, testing: revise docs for test flags In cmd/go's 'go help testflag': * Rewrite list of flags to drop test. prefix on every name. * Sort list of flags. * Add example of using -bench to match all benchmarks. In testing: * Remove mention of undefined 'CPU group' concept. Fixes #4488. Fixes #4508. R=adg CC=golang-dev https://golang.org/cl/7288053 --- diff --git a/src/cmd/go/test.go b/src/cmd/go/test.go index d3cfd1ad4c..48c77fc049 100644 --- a/src/cmd/go/test.go +++ b/src/cmd/go/test.go @@ -81,31 +81,47 @@ var helpTestflag = &Command{ The 'go test' command takes both flags that apply to 'go test' itself and flags that apply to the resulting test binary. -The test binary, called pkg.test, where pkg is the name of the -directory containing the package sources, has its own flags: +The following flags are recognized by the 'go test' command and +control the execution of any test: - -test.v - Verbose output: log all tests as they are run. - - -test.run pattern - Run only those tests and examples matching the regular - expression. - - -test.bench pattern + -bench regexp Run benchmarks matching the regular expression. - By default, no benchmarks run. + By default, no benchmarks run. To run all benchmarks, + use '-bench .' or '-bench=.'. - -test.benchmem + -benchmem Print memory allocation statistics for benchmarks. - -test.cpuprofile cpu.out + -benchtime t + Run enough iterations of each benchmark to take t, specified + as a time.Duration (for example, -benchtime 1h30s). + The default is 1 second (1s). + + -blockprofile block.out + Write a goroutine blocking profile to the specified file + when all tests are complete. + + -blockprofilerate n + Control the detail provided in goroutine blocking profiles by setting + runtime.BlockProfileRate to n. See 'godoc runtime BlockProfileRate'. + The profiler aims to sample, on average, one blocking event every + n nanoseconds the program spends blocked. By default, + if -test.blockprofile is set without this flag, all blocking events + are recorded, equivalent to -test.blockprofilerate=1. + + -cpu 1,2,4 + Specify a list of GOMAXPROCS values for which the tests or + benchmarks should be executed. The default is the current value + of GOMAXPROCS. + + -cpuprofile cpu.out Write a CPU profile to the specified file before exiting. - -test.memprofile mem.out + -memprofile mem.out Write a memory profile to the specified file when all tests are complete. - -test.memprofilerate n + -memprofilerate n Enable more precise (and expensive) memory profiles by setting runtime.MemProfileRate. See 'godoc runtime MemProfileRate'. To profile all memory allocations, use -test.memprofilerate=1 @@ -113,44 +129,35 @@ directory containing the package sources, has its own flags: garbage collector, provided the test can run in the available memory without garbage collection. - -test.blockprofile block.out - Write a goroutine blocking profile to the specified file - when all tests are complete. - - -test.blockprofilerate n - Control the detail provided in goroutine blocking profiles by setting - runtime.BlockProfileRate to n. See 'godoc runtime BlockProfileRate'. - The profiler aims to sample, on average, one blocking event every - n nanoseconds the program spends blocked. By default, - if -test.blockprofile is set without this flag, all blocking events - are recorded, equivalent to -test.blockprofilerate=1. - - -test.parallel n + -parallel n Allow parallel execution of test functions that call t.Parallel. The value of this flag is the maximum number of tests to run simultaneously; by default, it is set to the value of GOMAXPROCS. - -test.short + -run regexp + Run only those tests and examples matching the regular + expression. + + -short Tell long-running tests to shorten their run time. It is off by default but set during all.bash so that installing the Go tree can run a sanity check but not spend time running exhaustive tests. - -test.timeout t + -timeout t If a test runs longer than t, panic. - -test.benchtime t - Run enough iterations of each benchmark to take t. - The default is 1 second. + -v + Verbose output: log all tests as they are run. - -test.cpu 1,2,4 - Specify a list of GOMAXPROCS values for which the tests or - benchmarks should be executed. The default is the current value - of GOMAXPROCS. +The test binary, called pkg.test where pkg is the name of the +directory containing the package sources, can be invoked directly +after building it with 'go test -c'. When invoking the test binary +directly, each of the standard flag names must be prefixed with 'test.', +as in -test.run=TestMyFunc or -test.v. -For convenience, each of these -test.X flags of the test binary is -also available as the flag -X in 'go test' itself. Flags not listed -here are passed through unaltered. For instance, the command +When running 'go test', flags not listed above are passed through +unaltered. For instance, the command go test -x -v -cpuprofile=prof.out -dir=testdata -update diff --git a/src/pkg/testing/testing.go b/src/pkg/testing/testing.go index d24bf9b28f..d971f838e2 100644 --- a/src/pkg/testing/testing.go +++ b/src/pkg/testing/testing.go @@ -281,7 +281,7 @@ func (c *common) Fatalf(format string, args ...interface{}) { } // Parallel signals that this test is to be run in parallel with (and only with) -// other parallel tests in this CPU group. +// other parallel tests. func (t *T) Parallel() { t.signal <- (*T)(nil) // Release main testing loop <-t.startParallel // Wait for serial tests to finish