Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

proposal: testing: allow examples the use of testing.T/B/F for test framework examples #64993

hugelgupf opened this issue Jan 7, 2024 · 3 comments


Copy link

Proposal Details

Today, examples are tests presented alongside godoc as a "func main()" typically, as shown in, and is executable like that.

I'm trying to write examples for a test framework I created ( that requires the use of testing.TB. To create an executable example in, examples have to be able to take testing.T or testing.B as an argument.

IMO, the existing Example "API" should remain as is. If an example is given a testing.T/B/F argument, though, it should be assumed to require it and be presented that way in the documentation as well, e.g.

func ExampleFunctionname(t *testing.T) {
  // Output: foobar

Should appear alongside Functionname in documentation as an executable snippet like this:

package main_test

import (


func TestExample(t *testing.T) {
@gopherbot gopherbot added this to the Proposal milestone Jan 7, 2024
Copy link

earthboundkid commented Jan 9, 2024

I wrote a test framework and had this same problem. I usually use example driven development, but it was sort of hard to do that for a test framework. I had to make a dummy testing.TB, and it didn't always work very well. For example, testing.TB doesn't have T.Run, so I just stub that with code that compiles but doesn't execute.

Copy link

This seems fairly special purpose. Examples don't have to have outputs. Should we also permit example functions to take a slog.Logger argument? It seems hard to know when to stop.

Copy link

earthboundkid commented Feb 6, 2024

I think the proposal should be instead to make it easier to make a testing.T/B/F for test purposes. So the code would look like

func ExampleWhatever() {
    result := testing.RunTest(func(t *testing.T) {
        // do stuff with *testing.T
    fmt.Println("Test failed was", result.Failed, "because", result.Output)
    // Output: 
    // Test failed was true because error: bad potatoes

This could also be used in a TestFunction to test a testing framework more easily.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Status: Incoming

No branches or pull requests

4 participants