One change that comes to mind is adding a testing flag, so that go test doesn't run a slow example, but an explicit command like go test -slowexamples -run SlowExample does. That's probably a terrible solution, but it helps illustrate the two alternatives I'd like to have available somehow.

Edit: a slightly nicer flag would be go test -allexamples -run ExampleWithInternet.

You could probably about add a //build:slowexamples tag to those slow examples and then run them with go test -tag slowexamples -run "ExampleSlow.*". Would that solve your problem?

No; hiding the examples behind a build tag has the same issues as hiding them in an _examples package. They wouldn't show up in the godoc, and go test ./... wouldn't error if they can't build properly.

What about examples which are too slow or unreliable for go test, for example those needing access to the internet?

See previously the discussion on #30595, particularly #30595 (comment).

Unfortunately, unlike tests, runnable examples do not have a Short method to interrogate, nor a Skip method they can use to abort the example if it cannot be run. (They either have an Output line and always run, or they lack an Output line and always merely build.)

Thanks. I did see that thread, and I agree with Ian's response there. I don't think the same applies here; tests and examples are essentially different things. Generally, the users will be interested in the examples and will want to see and run them, regardless of whether they qualify as "slow" or "integration" examples.

I think there is a big difference between “see” and “run”.

I would argue that:

• go doc should show all examples in the documentation, regardless of their speed or requirements.
• go test should (by default) test only the subset of examples that are hermetic, leaving it up to users to explicitly enable the non-hermetic tests (by setting an environment variable or build tag).
• go test -short should test only the subset of examples that are both hermetic and fast.

The connection to Short and Skip is that we currently have no way to mark an example as “slow”, and no way to check only compilation for examples that should be runnable but not run by default.

What you said makes sense to me, for the most part. The only note I'd add is that I don't care about the speed of examples per se; I've rarely encountered an example which took a lot of resources or time. I should have probably titled this issue with "non-hermetic examples" instead of "slow examples". Or perhaps even "non-deterministic examples".

I should have probably titled this issue with "non-hermetic examples" instead of "slow examples". Or perhaps even "non-deterministic examples".

If that is the focus, then there might be some relationship to this comment from Russ in #23799 (comment)

It would be OK to have a 'mark this as depending on external things' as long as that result was still cached by default, and then we could also add a 'rerun all the tests that depend on external things' as an explicit flag. Not sure what that would look like exactly.

Leaving for Go 1.13.

Ok, I've retitled the issue to what I think is a better summary after the initial discussion.