From 89283781c69314f09e999fe131b12c57059c1ba1 Mon Sep 17 00:00:00 2001 From: Marcel van Lohuizen Date: Tue, 24 May 2016 20:03:31 +0200 Subject: [PATCH] testing: added package doc for sub(tests/benchmarks) Change-Id: I6991cd7a41140da784a1ff8d69c5ea2032d05850 Reviewed-on: https://go-review.googlesource.com/23354 Reviewed-by: Russ Cox Run-TryBot: Marcel van Lohuizen TryBot-Result: Gobot Gobot --- src/testing/testing.go | 55 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/src/testing/testing.go b/src/testing/testing.go index 9943fa6b4d..657a7b731f 100644 --- a/src/testing/testing.go +++ b/src/testing/testing.go @@ -118,6 +118,61 @@ // example function, at least one other function, type, variable, or constant // declaration, and no test or benchmark functions. // +// Subtests and Sub-benchmarks +// +// The Run methods of T and B allow defining subtests and sub-benchmarks, +// without having to define separate functions for each. This enables uses +// like table-driven benchmarks and creating hierarchical tests. +// It also provides a way to share common setup and tear-down code: +// +// func TestFoo(t *testing.T) { +// // +// t.Run("A=1", func(t *testing.T) { ... }) +// t.Run("A=2", func(t *testing.T) { ... }) +// t.Run("B=1", func(t *testing.T) { ... }) +// // +// } +// +// Each subtest and sub-benchmark has a unique name: the combination of the name +// of the top-level test and the sequence of names passed to Run, separated by +// slashes, with an optional trailing sequence number for disambiguation. +// +// The argument to the -run and -bench command-line flags is a slash-separated +// list of regular expressions that match each name element in turn. +// For example: +// +// go test -run Foo # Run top-level tests matching "Foo". +// go test -run Foo/A= # Run subtests of Foo matching "A=". +// go test -run /A=1 # Run all subtests of a top-level test matching "A=1". +// +// Subtests can also be used to control parallelism. A parent test will only +// complete once all of its subtests complete. In this example, all tests are +// run in parallel with each other, and only with each other, regardless of +// other top-level tests that may be defined: +// +// func TestGroupedParallel(t *testing.T) { +// for _, tc := range tests { +// tc := tc // capture range variable +// t.Run(tc.Name, func(t *testing.T) { +// t.Parallel() +// ... +// }) +// } +// } +// +// Run does not return until parallel subtests have completed, providing a way +// to clean up after a group of parallel tests: +// +// func TestTeardownParallel(t *testing.T) { +// // This Run will not return until the parallel tests finish. +// t.Run("group", func(t *testing.T) { +// t.Run("Test1", parallelTest1) +// t.Run("Test2", parallelTest2) +// t.Run("Test3", parallelTest3) +// }) +// // +// } +// // Main // // It is sometimes necessary for a test program to do extra setup or teardown -- 2.50.0