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: go test -help doesn't show test flags in Go 1.12 #30365

Closed
narqo opened this issue Feb 23, 2019 · 5 comments

Comments

Projects
None yet
5 participants
@narqo
Copy link
Contributor

commented Feb 23, 2019

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

$ go version
go version go1.12rc1 darwin/amd64

Does this issue reproduce with the latest release?

It doesn't (go1.11.5 darwin/amd64)

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

go env Output
$ go env
GOARCH="amd64"
GOBIN=""
GOCACHE="/Users/varankinv/Library/Caches/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/varankinv/.local/lib/go:/Users/varankinv/Workspace"
GOPROXY=""
GORACE=""
GOROOT="/Users/varankinv/.local/opt/go@1.12rc1"
GOTMPDIR=""
GOTOOLDIR="/Users/varankinv/.local/opt/go@1.12rc1/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/_v/1xkm5ft50dl0h1rs0rwxr7yc0000gn/T/go-build178856409=/tmp/go-build -gno-record-gcc-switches -fno-common"

What did you do?

Run go test -help

What did you expect to see?

Expected to see the list of all test flags, including those related to profiling, like -blockprofile, -cpuprofile, etc.

What did you see instead?

$ go test -help
usage: go test [build/test flags] [packages] [build/test flags & test binary flags]
Run 'go help test' for details.

Running go help test shows a general description of how test cmd works and has another note in the very end:

[..] The test binary also accepts flags that control execution of the test; these
flags are also accessible by 'go test'. See 'go help testflag' for details.

Indeed, go help testflag does contain the information in subject. But I believe it'd be nice for a user to have the reference to testflag help page in the go test -help output.

go help test
$ go help test
usage: go test [build/test flags] [packages] [build/test flags & test binary flags]

'Go test' automates testing the packages named by the import paths.
It prints a summary of the test results in the format:

	ok   archive/tar   0.011s
	FAIL archive/zip   0.022s
	ok   compress/gzip 0.033s
	...

followed by detailed output for each failed package.

'Go test' recompiles each package along with any files with names matching
the file pattern "*_test.go".
These additional files can contain test functions, benchmark functions, and
example functions. See 'go help testfunc' for more.
Each listed package causes the execution of a separate test binary.
Files whose names begin with "_" (including "_test.go") or "." are ignored.

Test files that declare a package with the suffix "_test" will be compiled as a
separate package, and then linked and run with the main test binary.

The go tool will ignore a directory named "testdata", making it available
to hold ancillary data needed by the tests.

As part of building a test binary, go test runs go vet on the package
and its test source files to identify significant problems. If go vet
finds any problems, go test reports those and does not run the test
binary. Only a high-confidence subset of the default go vet checks are
used. That subset is: 'atomic', 'bool', 'buildtags', 'nilfunc', and
'printf'. You can see the documentation for these and other vet tests
via "go doc cmd/vet". To disable the running of go vet, use the
-vet=off flag.

All test output and summary lines are printed to the go command's
standard output, even if the test printed them to its own standard
error. (The go command's standard error is reserved for printing
errors building the tests.)

Go test runs in two different modes:

The first, called local directory mode, occurs when go test is
invoked with no package arguments (for example, 'go test' or 'go
test -v'). In this mode, go test compiles the package sources and
tests found in the current directory and then runs the resulting
test binary. In this mode, caching (discussed below) is disabled.
After the package test finishes, go test prints a summary line
showing the test status ('ok' or 'FAIL'), package name, and elapsed
time.

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.

In package list mode only, go test caches successful package test
results to avoid unnecessary repeated running of tests. When the
result of a test can be recovered from the cache, go test will
redisplay the previous output instead of running the test binary
again. When this happens, go test prints '(cached)' in place of the
elapsed time in the summary line.

The rule for a match in the cache is that the run involves the same
test binary and the flags on the command line come entirely from a
restricted set of 'cacheable' test flags, defined as -cpu, -list,
-parallel, -run, -short, and -v. If a run of go test has any test
or non-test flags outside this set, the result is not cached. To
disable test caching, use any test flag or argument other than the
cacheable flags. The idiomatic way to disable test caching explicitly
is to use -count=1. Tests that open files within the package's source
root (usually $GOPATH) or that consult environment variables only
match future runs in which the files and environment variables are unchanged.
A cached test result is treated as executing in no time at all,
so a successful package test result will be cached and reused
regardless of -timeout setting.

In addition to the build flags, the flags handled by 'go test' itself are:

	-args
	    Pass the remainder of the command line (everything after -args)
	    to the test binary, uninterpreted and unchanged.
	    Because this flag consumes the remainder of the command line,
	    the package list (if present) must appear before this flag.

	-c
	    Compile the test binary to pkg.test but do not run it
	    (where pkg is the last element of the package's import path).
	    The file name can be changed with the -o flag.

	-exec xprog
	    Run the test binary using xprog. The behavior is the same as
	    in 'go run'. See 'go help run' for details.

	-i
	    Install packages that are dependencies of the test.
	    Do not run the test.

	-json
	    Convert test output to JSON suitable for automated processing.
	    See 'go doc test2json' for the encoding details.

	-o file
	    Compile the test binary to the named file.
	    The test still runs (unless -c or -i is specified).

The test binary also accepts flags that control execution of the test; these
flags are also accessible by 'go test'. See 'go help testflag' for details.

For more about build flags, see 'go help build'.
For more about specifying packages, see 'go help packages'.

See also: go build, go vet.
@mvdan

This comment has been minimized.

Copy link
Member

commented Feb 23, 2019

I believe this is on purpose; see @rsc's reply in #26999 (comment).

I agree it's a bit weird, but I also agree that go help test is already pretty massive.

@bcmills

This comment has been minimized.

Copy link
Member

commented Feb 25, 2019

go test -help should stay only two lines, but we could certainly reduce the number of hops required to get to go help testflag.

Perhaps something like:

usage: go test [build/test flags] [packages] [build/test flags & test binary flags]
Run 'go help test' and 'go help testflag' for details.

That said, the cmd/go docs could use a lot of simplification in general (#5044).

@narqo

This comment has been minimized.

Copy link
Contributor Author

commented Feb 25, 2019

I like the suggestion, it'd definitely solved my issue. Can open a CL if that makes sense.

@ianlancetaylor

This comment has been minimized.

Copy link
Contributor

commented Feb 25, 2019

@narqo Go for it. Thanks.

narqo added a commit to narqo/go that referenced this issue Feb 26, 2019

cmd/go: refer to testflag help in go test -help output
The change makes it easier for a user to get to the page where
she can check supported test flags, by adding 'go test testflag'
reference to the 'go test -help' output.

Fix golang#30365
@gopherbot

This comment has been minimized.

Copy link

commented Feb 26, 2019

Change https://golang.org/cl/163858 mentions this issue: cmd/go: refer to testflag help in go test -help output

@gopherbot gopherbot closed this in 249f5d2 Mar 1, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.