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

testing: clarity of -timeout flag #20927

Closed
vcabbage opened this issue Jul 6, 2017 · 2 comments
Closed

testing: clarity of -timeout flag #20927

vcabbage opened this issue Jul 6, 2017 · 2 comments

Comments

@vcabbage
Copy link
Member

vcabbage commented Jul 6, 2017

This is directly related to #20090, opening a new issue because I'm not sure whether closed issues are supposed to be reopened.

The description of the -timeout flag has changed twice for Go 1.9. The first change (done by me) was intended to clarify that the timeout applies per package. The latest revision, referring to "a test binary", is certainly correct, but in my experience many gophers do not know that the tests from each package is executed as a separate test binary. This can be inferred from the help text, but it's not explicit and likely to be ambiguous to many.

There may well be a better description than what I provided. I'd just like for the documentation to be clear without needing to understand exactly how test binaries are built and executed.

Original Text:

-timeout t
If a test runs longer than t, panic.
The default is 10 minutes (10m).

https://golang.org/cl/45816:

-timeout d
If the cumulative test time for a package runs longer than
duration d, panic. Timeout is disabled if set to 0.
The default is 10 minutes (10m).

https://golang.org/cl/47571:

-timeout d
If a test binary runs longer than duration d, panic.
The default is 10 minutes (10m).

Notes:

  • Emphasis added.
  • The "Timeout is disabled if set to 0" text can be ignored. It was a mistake on my part.
@vcabbage
Copy link
Member Author

vcabbage commented Jul 6, 2017

/cc @rsc

@bradfitz bradfitz added this to the Go1.9Maybe milestone Jul 6, 2017
@ianlancetaylor ianlancetaylor modified the milestones: Go1.10, Go1.9Maybe Aug 3, 2017
@rsc
Copy link
Contributor

rsc commented Dec 14, 2017

This appears to be about the phrase "test binary". That term is defined at the top of 'go help test' and used in multiple places throughout the test docs. It's impossible to make every help output stand alone. If one reads 'go help testflag' and don't understand what a test binary is, the natural next step would be 'go help test'? Or Google [test binary golang], whose first result is https://golang.org/cmd/go/. Given that it's a defined term, I don't think it's ambiguous, and I don't have a better one ('package test' is the obvious candidate but I think many people would expect that there are many package tests - every func TestFoo - for a given package; test binary is more clearly not a single test function).

@rsc rsc closed this as completed Dec 14, 2017
@golang golang locked and limited conversation to collaborators Dec 14, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

5 participants