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. This is inconvenient to write tests which are system dependent (ex: use of package os or time.Now()) where controlling a strict text output is not trivial. While it is possible to write the example to hide those system differences, that usually makes the example code much more verbose and so goes against the purpose of an example which has to be simple and clear.
*testing.T is a well known API to every Go developer so it fits the example scope for demonstrating features of a package.
EDIT: enriched rationale section
Comment From: gopherbot
Change https://go.dev/cl/679655 mentions this issue: go/doc: expose playable examples with a *testing.T parameter
Comment From: 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.