testing: explain how SkipNow and FailNow stop execution

SkipNow and FailNow must be called from the goroutine running the
test. This is already documented, but it's easy to call them by
mistake when writing subtests. In the following:

  func TestPanic(t *testing.T) {
    t.Run("", func(t2 *testing.T) {
	  t.FailNow()    // BAD: should be t2.FailNow()
	})
  }

the FailNow call on the outer t *testing.T correctly triggers a panic

  panic: test executed panic(nil) or runtime.Goexit

The error message confuses users (see issues #17421, #21175) because
there is no way to trace back the relevant part of the message ("test
executed ... runtime.Goexit") to a bad FailNow call without checking
the testing package source code and finding out that FailNow calls
runtime.Goexit.

To help users debug the panic message, mention in the SkipNow and
FailNow documentation that they stop execution by calling
runtime.Goexit.

Fixes #21175

Change-Id: I0a3e5f768e72b464474380cfffbf2b67396ac1b5
Reviewed-on: https://go-review.googlesource.com/52770
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/testing/testing.go b/src/testing/testing.go
index 11af926c80f8e9b69cc893c8317358c5057355bd..02b2d730eb5408874e9582decb326cc08b55d3bb 100644 (file)
--- a/src/testing/testing.go
+++ b/src/testing/testing.go
@@ -512,7 +512,8 @@ func (c *common) Failed() bool {
        return failed || c.raceErrors+race.Errors() > 0
 }
 
-// FailNow marks the function as having failed and stops its execution.
+// FailNow marks the function as having failed and stops its execution
+// by calling runtime.Goexit.
 // Execution will continue at the next test or benchmark.
 // FailNow must be called from the goroutine running the
 // test or benchmark function, not from other goroutines
@@ -600,7 +601,8 @@ func (c *common) Skipf(format string, args ...interface{}) {
        c.SkipNow()
 }
 
-// SkipNow marks the test as having been skipped and stops its execution.
+// SkipNow marks the test as having been skipped and stops its execution
+// by calling runtime.Goexit.
 // If a test fails (see Error, Errorf, Fail) and is then skipped,
 // it is still considered to have failed.
 // Execution will continue at the next test or benchmark. See also FailNow.