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

cmd/go: test Documentation: Package List Parallelisation #36741

Rossiar opened this issue Jan 24, 2020 · 2 comments

cmd/go: test Documentation: Package List Parallelisation #36741

Rossiar opened this issue Jan 24, 2020 · 2 comments


Copy link

@Rossiar Rossiar commented Jan 24, 2020

What version of Go are you using (go version)?

$ go version
go version go1.13.1 linux/amd64

Does this issue reproduce with the latest release?


What operating system and processor architecture are you using (go env)?

go env Output
$ go env
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build910819809=/tmp/go-build -gno-record-gcc-switches"

What did you do?

ran go help test which displays the go test documentation

What did you expect to see?

While running go test ./... in a project with many subpackages, I noticed that integration tests in each subpackage were failing (randomly) when accessing a shared resource (such as a database).

But if I ran the same code with go test ./... -p 1 I see that my packages run in sequential order and the failures do not occur. I am happy with this outcome and I understand why parallelization is the default when running in this mode, but I feel that this behaviour could be explicitly highlighted in the documentation to avoid confusion.

Right now the existing documentation comes close to covering this, but does not:

The second, called package list mode, occurs when go test is invoked
with explicit package arguments (for example 'go test math', 'go
test ./...', and even 'go test .'). In this mode, go test compiles
and tests each of the packages listed on the command line. If a
package test passes, go test prints only the final 'ok' summary
line. If a package test fails, go test prints the full test output.
If invoked with the -bench or -v flag, go test prints the full
output even for passing package tests, in order to display the
requested benchmark results or verbose logging. After the package
tests for all of the listed packages finish, and their output is
printed, go test prints a final 'FAIL' status if any package test
has failed.

What did you see instead?

The documentation doesn't cover the topic that I want to understand.

Let me know if an example project is necessary to illustrate this concept better, or if I can provide any further detail in writing. I didn't want to post an issue straight away for this, but the issues channel in golang slack that I checked hasn't seen any activity since last year, which indicates that it's not very well used.

@toothrot toothrot changed the title Go Test Documentation: Package List Parallelisation cmd/go: test Documentation: Package List Parallelisation Jan 24, 2020
@toothrot toothrot added this to the Backlog milestone Jan 24, 2020
Copy link

@toothrot toothrot commented Jan 24, 2020

It does mention In addition to the build flags, the flags handled by 'go test' itself are:. The help for go build covers this a bit:

	-p n
		the number of programs, such as build commands or
		test binaries, that can be run in parallel.
		The default is the number of CPUs available.

I'm not sure if an example project would be helpful, I think you've described the scenario clearly enough, thanks!

Do you have a specific suggestion on what could be improved? I understand that your scenario is different, but ideally people do not have to manipulate this, as avoiding order dependency in testing is a feature in my opinion.

/cc @bcmills @jayconrod

Copy link

@Rossiar Rossiar commented Jan 27, 2020

I would just add this definition of the -p flag to the list shown when running go help test - along with this could be an addition to the existing text around package list mode:

...In this mode, go test compiles and tests each of the packages listed on the command line, this can occur sequentially or in parallel depending on the value of the -p flag and number of CPUs available.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants