From 10d855198cb57154301aecd02f0c195cad2483b9 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Fri, 16 Jun 2017 11:16:37 -0400 Subject: [PATCH] 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 Reviewed-by: Brad Fitzpatrick --- src/cmd/go/alldocs.go | 27 ++++++++++++++++++--------- src/cmd/go/internal/test/test.go | 27 ++++++++++++++++++--------- 2 files changed, 36 insertions(+), 18 deletions(-) diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index 30af611b53..beda85860d 100644 --- 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 3575cad204..38b7e3fda3 100644 --- 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.