testing: add Attr

Add a new Attr method to testing.TB that emits a test attribute.
An attribute is an arbitrary key/value pair.

Fixes #43936

Change-Id: I7ef299efae41f2cf39f2dc61ad4cdd4c3975cdb6
Reviewed-on: https://go-review.googlesource.com/c/go/+/662437
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
Auto-Submit: Damien Neil <dneil@google.com>

1 files changed, 26 insertions, 0 deletions

diff --git a/src/testing/testing.go b/src/testing/testing.go
index 13f19a2a22..85ac1aeb32 100644
--- a/src/testing/testing.go
+++ b/src/testing/testing.go
@@ -879,6 +879,7 @@ func fmtDuration(d time.Duration) string {
 
 // TB is the interface common to [T], [B], and [F].
 type TB interface {
+	Attr(key, value string)
 	Cleanup(func())
 	Error(args ...any)
 	Errorf(format string, args ...any)
@@ -1491,6 +1492,31 @@ func (c *common) Context() context.Context {
 	return c.ctx
 }
 
+// Attr emits a test attribute associated with this test.
+//
+// The key must not contain whitespace.
+// The value must not contain newlines or carriage returns.
+//
+// The meaning of different attribute keys is left up to
+// continuous integration systems and test frameworks.
+//
+// Test attributes are emitted immediately in the test log,
+// but they are intended to be treated as unordered.
+func (c *common) Attr(key, value string) {
+	if strings.ContainsFunc(key, unicode.IsSpace) {
+		c.Errorf("disallowed whitespace in attribute key %q", key)
+		return
+	}
+	if strings.ContainsAny(value, "\r\n") {
+		c.Errorf("disallowed newline in attribute value %q", value)
+		return
+	}
+	if c.chatty == nil {
+		return
+	}
+	c.chatty.Updatef(c.name, "=== ATTR  %s %v %v\n", c.name, key, value)
+}
+
 // panicHandling controls the panic handling used by runCleanup.
 type panicHandling int