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 d3cfd1ad4cd64ad0c79a679fe14d2279f859338a..48c77fc0492f9108ed7e8fb048f849a579bd734c 100644 (file)
--- 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 d24bf9b28f8975ed4bd6eb5cafb7b3b298e0cb07..d971f838e2b3cc7d3c0ae9aa13eddad81d45dcd3 100644 (file)
--- 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