gotestsum
gotestsum runs tests, prints friendly test output and a summary of the test run. Requires Go 1.10+.
Install
Download a binary from releases, or from
source with go get gotest.tools/gotestsum (you may need to run dep ensure if your version of Go
does not support modules).
Demo
A demonstration of three --format options.
Docs
gotestsum works by running go test --json ./... and reading the JSON
output.
TOC
- Format
- Summary
- JUnit XML
- JSON file
- Using go test flags and custom commands
- Executing a compiled test binary
Format
Set a format with the --format flag or the GOTESTSUM_FORMAT environment
variable.
gotestsum --format short-verbose
Supported formats:
dots- print a character for each test.short(default) - print a line for each package.short-with-failures- print a line for each package and failed test output.short-verbose- print a line for each test and package.standard-quiet- the standardgo testformat.standard-verbose- the standardgo test -vformat.
Have a suggestion for some other format? Please open an issue!
Summary
A summary of the test run is printed after the test output.
DONE 101 tests[, 3 skipped][, 2 failures][, 1 error] in 0.103s
The summary includes:
- A count of: tests run, tests skipped, tests failed, and package build errors.
- Elapsed time including time to build.
- Test output of all failed and skipped tests, and any package build errors.
To disable parts of the summary use --no-summary section.
Example: hide skipped tests in the summary
gotestsum --no-summary=skipped
Example: hide failed and skipped
gotestsum --no-summary=skipped,failed
Example: hide output in the summary, only print names of failed and skipped tests
and errors
gotestsum --no-summary=output
JUnit XML
When the --junitfile flag or GOTESTSUM_JUNITFILE environment variable are set
to a file path gotestsum will write a test report, in JUnit XML format, to the file.
This file can be used to integrate with CI systems.
gotestsum --junitfile unit-tests.xml
If the package names in the testsuite.name or testcase.classname fields do not
work with your CI system these values can be customized using the
--junitfile-testsuite-name, or --junitfile-testcase-classname flags. These flags
accept the following values:
short- the base name of the package (the single term specified by the
package statement).relative- a package path relative to the root of the repositoryfull- the full package path (default)
Note: If Go is not installed, or the go binary is not in PATH, the GOVERSION
environment variable can be set to remove the "failed to lookup go version for junit xml"
warning.
JSON file output
When the --jsonfile flag or GOTESTSUM_JSONFILE environment variable are set
to a file path gotestsum will write a line-delimited JSON file with all the
test2json
output that was written by go test --json. This file can be used to compare test
runs, or find flaky tests.
gotestsum --jsonfile test-output.log
Custom go test command
By default gotestsum runs tests using the command go test --json ./.... You
can change the command with positional arguments after a --. You can change just the
test directory value (which defaults to ./...) by setting the TEST_DIRECTORY
environment variable.
You can use --debug to echo the command before it is run.
Example: set build tags
gotestsum -- -tags=integration ./...
Example: run tests in a single package
gotestsum -- ./io/http
Example: enable coverage
gotestsum -- -coverprofile=cover.out ./...
Example: run a script instead of go test
gotestsum --raw-command -- ./scripts/run_tests.sh
Note: when using --raw-command you must ensure that the stdout produced by
the script only contains the test2json output. Any stderr produced by the script
will be considered an error (this behaviour is necessary because package build errors
are only reported by writting to stderr, not the test2json stdout). Any stderr
produced by tests is not considered an error (it will be in the test2json stdout).
Example: using TEST_DIRECTORY
TEST_DIRECTORY=./io/http gotestsum
Executing a compiled test binary
gotestsum supports executing a compiled test binary (created with go test -c) by running
it as a custom command.
The -json flag is handled by go test itself, it is not available when using a
compiled test binary, so go tool test2json must be used to get the output
that gotestsum expects.
Example:
gotestsum --raw-command -- go tool test2json -p pkgname ./binary.test -test.v
pkgname is the name of the package being tested, it will show up in the test
output. ./binary.test is the path to the compiled test binary. The -test.v
must be included so that go tool test2json receives all the output.
To execute a test binary without installing Go, see
running without go.
Run tests when a file is modified
filewatcher will automatically set the
TEST_DIRECTORY environment variable which makes it easy to integrate
gotestsum.
Example: run tests for a package when any file in that package is saved
filewatcher gotestsum
Thanks
This package is heavily influenced by the pytest test runner for python.