proposal: go/doc,testing: add playable examples using a *testing.T context

[dolmen]

Proposal Details

Goal

Allow documentation/example writers to expose testable examples that run with a *testing.T context. That would be helpful to write richer examples as they would benefit from the well-known *testing.T API, which provides more flexible assertions infrastructure than just checking stdout result (for existing testable examples).

Proposed solution

Expose exported functions with prefix Example and signature func(*testing.T) as testable examples in a similar way to Example funcs. They would be displayed by x/pkgsite (like on https://pkg.go.dev) with a Test prefix replacing Example.

Such Example...(t *testing.T) would be executed by go test like standard Test...(*testing.T) tests.

Rationale

Testable examples are very useful for documenting the features of a package as they allow the reader to directly play with the API.

The Go Playground (code: golang.org/x/playground) supports running programs with a main, but also code that instead defines a Test* function with a *testing.T argument (example: https://go.dev/play/p/ECwmV7-1Ohx).

Connecting both would allow to provide richer examples, using existing infrastructure of the Go Playground, and in the spirit of the existing testable examples.

Why *testing.T?

Examples expressed as standard tests are much more flexible in how to express assertions. In standard testable examples the only assertion possible is matching of stdout output.

Here are a few case where strict text matching is not convenient because that usually makes the example code much more verbose (to filter/transform/truncate output) and so goes against the purpose of an example which has to be simple and clear:

• examples that are system dependent (ex: use of package os or time.Now())
• examples that produce binary content
• examples that produce long content

*testing.T is a well known API to every Go developer so it fits the example scope for demonstrating features of a package. t.Fatal is a clean way to properly handle unexpected errors without verbosity.

EDIT: enriched rationale section

[gopherbot]

Change https://go.dev/cl/679655 mentions this issue: go/doc: expose playable examples with a *testing.T parameter

[dolmen]

@seankhliao As this proposal is more scoped than #64993 and has a partial implementation in CL 679655, I suggest to detach it from #64993 for the review process.