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.

Sign up for GitHub

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

Jump to bottom

testing: the overview documentation on (*T) Run is unclear #35824

Closed
ghost opened this issue Nov 25, 2019 · 3 comments
Closed

testing: the overview documentation on (*T) Run is unclear #35824

ghost opened this issue Nov 25, 2019 · 3 comments
Labels
Documentation Issues describing a change to documentation. NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Backlog

Comments

@ghost
Copy link

ghost commented Nov 25, 2019

The package documentation says that

// Run does not return until parallel subtests have completed

But that means that in the example above (see below) the tests aren't run in parallel, because "Run does not return", which I take to mean that the first Run blocks (and then the second too, etc):

//     func TestGroupedParallel(t *testing.T) {
//         for _, tc := range tests {
//             tc := tc // capture range variable
//             t.Run(tc.Name, func(t *testing.T) {
//                 t.Parallel()
//                 ...
//             })
//         }
//     }
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Nov 25, 2019
@toothrot toothrot added this to the Backlog milestone Nov 26, 2019
@toothrot
Copy link
Contributor

@opennota I feel like the documentation for T.Run itself is fairly clear on this behavior:

https://pkg.go.dev/testing?tab=doc#T.Run

Run runs f as a subtest of t called name. It runs f in a separate goroutine and blocks until f returns or calls t.Parallel to become a parallel test. Run reports whether f succeeded (or at least did not fail before calling t.Parallel).
Run may be called simultaneously from multiple goroutines, but all such calls must return before the outer test function for t returns.

Do you have a suggestion for improving this?

Also, if you're curious, you can see the go running the tests here: https://github.com/golang/go/blob/go1.13.4/src/testing/testing.go#L960

@toothrot toothrot added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Nov 26, 2019
@ghost
Copy link
Author

ghost commented Nov 26, 2019

This is clear enough:

blocks until f returns or calls t.Parallel to become a parallel test.

but the package documentation which I'm talking about comes first and if one reads from the start can confuse him.

@toothrot toothrot changed the title testing: the documentation on Run is unclear testing: the overview documentation on (*T) Run is unclear Nov 27, 2019
@toothrot
Copy link
Contributor

/cc @mpvl @josharian

@seankhliao seankhliao closed this as not planned Won't fix, can't repro, duplicate, stale Dec 3, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
3 participants
@toothrot @gopherbot @seankhliao