cmd/go: clarify test -run and -bench pattern matching

Make it clearer that -test=X/Y runs all the tests matching X,
even if they don't have sub-tests matching Y.

Fixes #20589.

Change-Id: Ic27e89e748d60f67b50c68445ec0480066bdf207
Reviewed-on: https://go-review.googlesource.com/46030
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 30af611b53274a613e1cce662df5ab4a83c86f54..beda85860d7a36efd6a6a37f32715b856c18d1ff 100644 (file)
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -1417,12 +1417,17 @@
 // control the execution of any test:
 //
 //     -bench regexp
-//         Run (sub)benchmarks matching a regular expression.
-//         The given regular expression is split into smaller ones by
-//         top-level '/', where each must match the corresponding part of a
-//         benchmark's identifier.
-//         By default, no benchmarks run. To run all benchmarks,
-//         use '-bench .' or '-bench=.'.
+//         Run only those benchmarks matching a regular expression.
+//         By default, no benchmarks are run.
+//         To run all benchmarks, use '-bench .' or '-bench=.'.
+//         The regular expression is split by unbracketed slash (/)
+//         characters into a sequence of regular expressions, and each
+//         part of a benchmark's identifier must match the corresponding
+//         element in the sequence, if any. Possible parents of matches
+//         are run with b.N=1 to identify sub-benchmarks. For example,
+//         given -bench=X/Y, top-level benchmarks matching X are run
+//         with b.N=1 to find any sub-benchmarks matching Y, which are
+//         then run in full.
 //
 //     -benchtime t
 //         Run enough iterations of each benchmark to take t, specified
@@ -1479,9 +1484,13 @@
 //
 //     -run regexp
 //         Run only those tests and examples matching the regular expression.
-//         For tests the regular expression is split into smaller ones by
-//         top-level '/', where each must match the corresponding part of a
-//         test's identifier.
+//         For tests, the regular expression is split by unbracketed slash (/)
+//         characters into a sequence of regular expressions, and each part
+//         of a test's identifier must match the corresponding element in
+//         the sequence, if any. Note that possible parents of matches are
+//         run too, so that -run=X/Y matches and runs and reports the result
+//         of all tests matching X, even those without sub-tests matching Y,
+//         because it must run them to look for those sub-tests.
 //
 //     -short
 //         Tell long-running tests to shorten their run time.

diff --git a/src/cmd/go/internal/test/test.go b/src/cmd/go/internal/test/test.go
index 3575cad20461fa54736147a970fbbe874ce3a379..38b7e3fda3e7cf4f09e4262934ac7c0da7db4c15 100644 (file)
--- a/src/cmd/go/internal/test/test.go
+++ b/src/cmd/go/internal/test/test.go
@@ -142,12 +142,17 @@ control the execution of any test:
 
 const testFlag2 = `
        -bench regexp
-           Run (sub)benchmarks matching a regular expression.
-           The given regular expression is split into smaller ones by
-           top-level '/', where each must match the corresponding part of a
-           benchmark's identifier.
-           By default, no benchmarks run. To run all benchmarks,
-           use '-bench .' or '-bench=.'.
+           Run only those benchmarks matching a regular expression.
+           By default, no benchmarks are run. 
+           To run all benchmarks, use '-bench .' or '-bench=.'.
+           The regular expression is split by unbracketed slash (/)
+           characters into a sequence of regular expressions, and each
+           part of a benchmark's identifier must match the corresponding
+           element in the sequence, if any. Possible parents of matches
+           are run with b.N=1 to identify sub-benchmarks. For example,
+           given -bench=X/Y, top-level benchmarks matching X are run
+           with b.N=1 to find any sub-benchmarks matching Y, which are
+           then run in full.
 
        -benchtime t
            Run enough iterations of each benchmark to take t, specified
@@ -204,9 +209,13 @@ const testFlag2 = `
 
        -run regexp
            Run only those tests and examples matching the regular expression.
-           For tests the regular expression is split into smaller ones by
-           top-level '/', where each must match the corresponding part of a
-           test's identifier.
+           For tests, the regular expression is split by unbracketed slash (/)
+           characters into a sequence of regular expressions, and each part
+           of a test's identifier must match the corresponding element in
+           the sequence, if any. Note that possible parents of matches are
+           run too, so that -run=X/Y matches and runs and reports the result
+           of all tests matching X, even those without sub-tests matching Y,
+           because it must run them to look for those sub-tests.
 
        -short
            Tell long-running tests to shorten their run time.