Description
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
ortime.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