testing: Add T.ExpectFail()

ExpectFail() signals a test is expected to fail. The PASS/FAIL result is
inverted; passing tests fail, failing tests pass.

Author: 13rac1

src/testing/sub_test.go

@@ -315,6 +315,29 @@ func TestTRun(t *T) {
 		f: func(t *T) {
 			t.Skip()
 		},
+	}, {
+		desc: "expect fail, get fail",
+		ok:   true,
+		f: func(t *T) {
+			t.ExpectFail()
+			t.Fail()
+		},
+	}, {
+		desc: "expect panic fail, get panic fail",
+		ok:   true,
+		f: func(t *T) {
+			t.ExpectFail()
+			panic("expected panic")
+		},
+	}, {
+		desc: "expect fail, no fail",
+		ok:   false,
+		output: `
+--- FAIL: expect fail, no fail (N.NNs)
+    testing.go:NNN: expected failure; test did not fail`,
+		f: func(t *T) {
+			t.ExpectFail()
+		},
 	}, {
 		desc: "subtest calls error on parent",
 		ok:   false,

src/testing/testing.go

@@ -300,14 +300,15 @@ const maxStackLen = 50
 // common holds the elements common between T and B and
 // captures common methods such as Errorf.
 type common struct {
-	mu      sync.RWMutex        // guards this group of fields
-	output  []byte              // Output generated by test or benchmark.
-	w       io.Writer           // For flushToParent.
-	ran     bool                // Test or benchmark (or one of its subtests) was executed.
-	failed  bool                // Test or benchmark has failed.
-	skipped bool                // Test of benchmark has been skipped.
-	done    bool                // Test is finished and all subtests have completed.
-	helpers map[string]struct{} // functions to be skipped when writing file/line info
+	mu         sync.RWMutex        // guards this group of fields
+	output     []byte              // Output generated by test or benchmark.
+	w          io.Writer           // For flushToParent.
+	ran        bool                // Test or benchmark (or one of its subtests) was executed.
+	failed     bool                // Test or benchmark has failed.
+	expectFail bool                // Test is expected to fail.
+	skipped    bool                // Test or benchmark has been skipped.
+	done       bool                // Test is finished and all subtests have completed.
+	helpers    map[string]struct{} // functions to be skipped when writing file/line info
 
 	chatty     bool   // A copy of the chatty flag.
 	finished   bool   // Test function has completed.
@@ -526,8 +527,8 @@ var _ TB = (*B)(nil)
 //
 // A test ends when its Test function returns or calls any of the methods
 // FailNow, Fatal, Fatalf, SkipNow, Skip, or Skipf. Those methods, as well as
-// the Parallel method, must be called only from the goroutine running the
-// Test function.
+// the Parallel and ExpectFail methods, must be called only from the goroutine
+// running the Test function.
 //
 // The other reporting methods, such as the variations of Log and Error,
 // may be called simultaneously from multiple goroutines.
@@ -555,7 +556,8 @@ func (c *common) setRan() {
 
 // Fail marks the function as having failed but continues execution.
 func (c *common) Fail() {
-	if c.parent != nil {
+	// Fail the parent if the failure is unexpected.
+	if c.parent != nil && !c.expectFail {
 		c.parent.Fail()
 	}
 	c.mu.Lock()
@@ -784,6 +786,22 @@ func (t *T) Parallel() {
 	t.raceErrors += -race.Errors()
 }
 
+// ExpectFail signals that this test is expected to fail. The PASS/FAIL result
+// is inverted; passing tests fail, failing tests pass. Use for bug reproduction
+// or documentation of unimplemented features.
+func (t *T) ExpectFail() {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.expectFail = true
+}
+
+// unfail resets a test failure. Used when the failure was expected.
+func (t *T) unfail() {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.failed = false
+}
+
 // An internal type but exported because it is cross-package; part of the implementation
 // of the "go test" command.
 type InternalTest struct {
@@ -825,9 +843,31 @@ func tRunner(t *T, fn func(t *T)) {
 			}
 		}
 		if err != nil {
-			t.Fail()
-			t.report()
-			panic(err)
+			if t.expectFail {
+				// Set failure, but do not die.
+				t.Errorf("panic: %s", err)
+			} else {
+				t.Fail()
+				t.report()
+				panic(err)
+			}
+		}
+
+		if t.expectFail {
+			if t.failed {
+				// Test passes
+				t.Log("expected failure; test failed")
+				t.unfail()
+			} else {
+				t.Error("expected failure; test did not fail")
+				// Fail parent because it was skipped earlier.
+				if t.parent != nil {
+					t.parent.Fail()
+				}
+
+				// Increment because it was skipped.
+				atomic.AddUint32(&numFailed, 1)
+			}
 		}
 
 		if len(t.sub) > 0 {