gotestsum

You can install gotestsum by building from source using go install, or run it directly without installation using go run.

To install the binary to your $GOPATH/bin:

go install gotest.tools/gotestsum@latest

To run it without installing:

go run gotest.tools/gotestsum@latest

Alternatively, you can download a pre-compiled binary from the releases page.

Use the --format flag or the GOTESTSUM_FORMAT environment variable to control how test names and output are printed. Most formats use color to highlight pass, fail, or skip status.

Commonly used formats:

• dots: Prints a character for each test.
• pkgname (default): Prints a line for each package.
• testname: Prints a line for each test and package.
• testdox: Prints a sentence for each test using gotestdox.
• standard-quiet: The standard go test format.
• standard-verbose: The standard go test -v format.

You can also change the icons used by pkgname and testdox formats using the --format-icons flag or the GOTESTSUM_FORMAT_ICONS environment variable. Note that Nerd Fonts icons require a Nerd Font to be installed.

gotestsum --format dots

The gotestsum CLI is a wrapper around go test that provides enhanced output formats, JUnit XML generation, test rerunning, and file watching.

Usage Pattern:

# Basic usage (runs all tests in current directory)
gotestsum

# Running specific packages with custom go test flags
gotestsum -- [go test flags] [packages]

# Using a specific output format
gotestsum --format dots

The rerun-fails functionality allows you to automatically re-execute only the tests that failed during a previous run. This is useful for debugging flaky tests.

Key behaviors:

• It uses -test.run flags to target specific failed tests or subtests.
• It can be configured to re-run only the root test cases (ignoring subtests) if rerunFailsRunRootCases is enabled.
• It supports multiple attempts up to a specified maximum.
• It can abort the re-run if it detects a panic or a data race (if rerunFailsAbortOnDataRace is enabled).

You can execute a custom command after the test run completes using postRunHookCmd. The command is executed with the following environment variables available to it:

The command's stdout and stderr are piped to the same streams as gotestsum.

The matrix tool reads a list of Go packages from stdin and analyzes previous test run timings from log files to output a JSON object. This JSON object can be used as a GitHub Actions matrix strategy to split test packages into parallel partitions, minimizing overall CI runtime by balancing the workload based on historical execution times.

To use it in a GitHub Actions workflow, pipe the list of packages (e.g., via go list ./...) into the tool and redirect the output to $GITHUB_OUTPUT.

Usage Example

echo -n "matrix=" >> $GITHUB_OUTPUT
go list ./... | matrix --timing-files ./*.log --partitions 4 >> $GITHUB_OUTPUT

The slowest tool reads test output in JSON format (generated by gotestsum --jsonfile or go test -json) and identifies tests that exceed a specified time threshold.

By default, it prints a list of slow tests to stdout, sorted from slowest to fastest. If the --skip-stmt flag is provided, the tool modifies the Go source code in your working directory to inject a skip statement into the slow test functions, allowing you to bypass them in future runs.

To run a test binary created with go test -c, use --raw-command combined with go tool test2json to convert the binary's output into the JSON format gotestsum expects.

Note: You must include the -test.v flag for test2json to work correctly.

gotestsum --raw-command -- go tool test2json -t -p pkgname ./binary.test -test.v

If rerunFailsMaxAttempts is greater than 0 and a report file path is provided via rerunFailsReportFile, gotestsum will generate a report summarizing the results of the re-runs. The report format is:

<package>.<test_name>: <total_runs> runs, <failure_count> failures

Example report line: github.com/user/repo/pkg.TestExample: 3 runs, 1 failures

You can instruct gotestsum to write test events to JSON files. This is useful for machine-readable logs and post-processing.

• jsonFile: The path to the file where all test events will be written (one JSON object per line).
• jsonFileTimingEvents: The path to a file where only terminal test events (events that mark the end of a test) are written. This is useful for analyzing test durations.