From 8f4bc468a7f5846149d7f0b51633c6fea3861515 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch Date: Fri, 16 Nov 2018 02:20:58 +0000 Subject: [PATCH] testing: add example to package doc The package doc for the testing package doesn't have a simple example demonstrating how to write a test with an expectation. The doc has simple examples for benchmarks, examples, and skipping, and it would be useful for people new to writing tests in Go. Also moved the skip example further down because it references tests and benchmarks but benchmarks haven't been discussed in detail until the next section. Skip is also a less used feature and it seems misplaced to sit so high up in the package documentation. As an example, Skip is used 570 times the Go code repository which is significantly less than Error and Fatal that are used 23,303 times. Also changed 'sample' to 'simple' in other places in the package documentation to keep the language used consistent when describing the small examples. Fixes #27839 Change-Id: Ie01a3751986ee61adf2a2f2eda59cc182342baa7 GitHub-Last-Rev: 7357bfdcd29ed1dc1719c9436b5d5420020610ee GitHub-Pull-Request: golang/go#27840 Reviewed-on: https://go-review.googlesource.com/c/137175 Run-TryBot: Brad Fitzpatrick TryBot-Result: Gobot Gobot Reviewed-by: Brad Fitzpatrick Reviewed-by: Emmanuel Odeke --- src/testing/testing.go | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/src/testing/testing.go b/src/testing/testing.go index 0bc222c0bb..0ac51b6fe5 100644 --- a/src/testing/testing.go +++ b/src/testing/testing.go @@ -17,13 +17,13 @@ // package builds but will be included when the ``go test'' command is run. // For more detail, run ``go help test'' and ``go help testflag''. // -// Tests and benchmarks may be skipped if not applicable with a call to -// the Skip method of *T and *B: -// func TestTimeConsuming(t *testing.T) { -// if testing.Short() { -// t.Skip("skipping test in short mode.") +// A simple test function looks like this: +// +// func TestAbs(t *testing.T) { +// got := Abs(-1) +// if got != 1 { +// t.Errorf("Abs(-1) = %d; want 1", got) // } -// ... // } // // Benchmarks @@ -132,6 +132,18 @@ // example function, at least one other function, type, variable, or constant // declaration, and no test or benchmark functions. // +// Skipping +// +// Tests or benchmarks may be skipped at run time with a call to +// the Skip method of *T or *B: +// +// func TestTimeConsuming(t *testing.T) { +// if testing.Short() { +// t.Skip("skipping test in short mode.") +// } +// ... +// } +// // Subtests and Sub-benchmarks // // The Run methods of T and B allow defining subtests and sub-benchmarks, -- 2.50.0