Skip to main content
Version: 2.23 (prerelease)

go-test

Options for Go tests.

Backend: pants.backend.experimental.go.lint.vet

Config section: [go-test]

Basic options​

args​

--go-test-args="[<shell_str>, <shell_str>, ...]", ... -- [<shell_str> [<shell_str> [...]]]
PANTS_GO_TEST_ARGS
pants.toml
[go-test]
args = [
    <shell_str>,
    <shell_str>,
    ...,
]
default: []

Arguments to pass directly to Go test binary, e.g. --go-test-args='-run TestFoo -v'.

Known Go test options will be transformed into the form expected by the test binary, e.g. -v becomes -test.v. Run go help testflag from the Go SDK to learn more about the options supported by Go test binaries.

block_profile​

--[no-]go-test-block-profile
PANTS_GO_TEST_BLOCK_PROFILE
pants.toml
[go-test]
block_profile = <bool>
default: False

Capture a goroutine blocking profile from the execution of the test runner. The profile will be written to the file block.out in the test extra output directory. The test binary will also be written to the test extra output directory.

cover_mode​

--go-test-cover-mode=<GoCoverMode>
PANTS_GO_TEST_COVER_MODE
pants.toml
[go-test]
cover_mode = <GoCoverMode>
one of: set, count, atomic
default: set

Coverage mode to use when running Go tests with coverage analysis enabled via --test-use-coverage. Valid values are set, count, and atomic:

  • set: bool: does this statement run?
  • count: int: how many times does this statement run?
  • atomic: int: count, but correct in multithreaded tests; significantly more expensive.

coverage_html​

--[no-]go-test-coverage-html
PANTS_GO_TEST_COVERAGE_HTML
pants.toml
[go-test]
coverage_html = <bool>
default: True

If true, then convert coverage reports to HTML format and write a coverage.html file next to the raw coverage data.

coverage_packages​

--go-test-coverage-packages="['<str>', '<str>', ...]"
PANTS_GO_TEST_COVERAGE_PACKAGES
pants.toml
[go-test]
coverage_packages = [
    '<str>',
    '<str>',
    ...,
]
default: []

A list of "import path patterns" for determining which import paths will be instrumented for code coverage.

From go help packages:

An import path is a pattern if it includes one or more "..." wildcards, each of which can match any string, including the empty string and strings containing slashes. Such a pattern expands to all package directories found in the GOPATH trees with names matching the patterns.

To make common patterns more convenient, there are two special cases. First, /... at the end of the pattern can match an empty string, so that net/... matches both net and packages in its subdirectories, like net/http. Second, any slash-separated pattern element containing a wildcard never participates in a match of the "vendor" element in the path of a vendored package, so that ./... does not match packages in subdirectories of ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do. Note, however, that a directory named vendor that itself contains code is not a vendored package: cmd/vendor would be a command named vendor, and the pattern cmd/... matches it. See golang.org/s/go15vendor for more about vendoring.

This option is similar to the go test -coverpkg option, but without support currently for reserved import path patterns like std and all.

cpu_profile​

--[no-]go-test-cpu-profile
PANTS_GO_TEST_CPU_PROFILE
pants.toml
[go-test]
cpu_profile = <bool>
default: False

Capture a CPU profile from the execution of the test runner. The profile will be written to the file cpu.out in the test extra output directory. The test binary will also be written to the test extra output directory.

force_asan​

--[no-]go-test-force-asan
PANTS_GO_TEST_FORCE_ASAN
pants.toml
[go-test]
force_asan = <bool>
default: False

If true, then always enable interoperation between Go and the C/C++ "address sanitizer" when running tests regardless of the test-by-test asan field on the relevant go_package target.

See https://github.com/google/sanitizers/wiki/AddressSanitizer for additional information about the C/C++ address sanitizer.

force_msan​

--[no-]go-test-force-msan
PANTS_GO_TEST_FORCE_MSAN
pants.toml
[go-test]
force_msan = <bool>
default: False

If true, then always enable interoperation between Go and the C/C++ "memory sanitizer" when running tests regardless of the test-by-test msan field on the relevant go_package target.

See https://github.com/google/sanitizers/wiki/MemorySanitizer for additional information about the C/C++ memory sanitizer.

force_race​

--[no-]go-test-force-race
PANTS_GO_TEST_FORCE_RACE
pants.toml
[go-test]
force_race = <bool>
default: False

If true, then always enable the Go data race detector when running tests regardless of the test-by-test test_race field on the relevant go_package target.

See https://go.dev/doc/articles/race_detector for additional information about the Go data race detector.

mem_profile​

--[no-]go-test-mem-profile
PANTS_GO_TEST_MEM_PROFILE
pants.toml
[go-test]
mem_profile = <bool>
default: False

Capture an allocation profile from the execution of the test runner after tests have passed. The profile will be written to the file mem.out in the test extra output directory. The test binary will also be written to the test extra output directory.

mutex_profile​

--[no-]go-test-mutex-profile
PANTS_GO_TEST_MUTEX_PROFILE
pants.toml
[go-test]
mutex_profile = <bool>
default: False

Capture a mutex contention profile from the execution of the test runner when all tests are complete. The profile will be written to the file mutex.out in the test extra output directory. The test binary will also be written to the test extra output directory.

skip​

--[no-]go-test-skip
PANTS_GO_TEST_SKIP
pants.toml
[go-test]
skip = <bool>
default: False

If true, don't use Go test binary when running pants test.

trace​

--[no-]go-test-trace
PANTS_GO_TEST_TRACE
pants.toml
[go-test]
trace = <bool>
default: False

Capture an execution trace from the execution of the test runner. The trace will be written to the file trace.out in the test extra output directory.

Advanced options​

coverage_output_dir​

--go-test-coverage-output-dir=<str>
PANTS_GO_TEST_COVERAGE_OUTPUT_DIR
pants.toml
[go-test]
coverage_output_dir = <str>
default: {distdir}/coverage/go/{target_spec}

Path to write the Go coverage reports to. Must be relative to the build root.

Replacements:

  • {distdir} is replaced with the Pants distdir.
  • {target_spec} is replaced with the address of the applicable go_package target with / characters replaced with dots (.).
  • {import_path} is replaced with the applicable package's import path. Subdirectories will be made for any path components separated by / characters.
  • {import_path_escaped} is replaced with the applicable package's import path but with slashes converted to underscores. This is deprecated and only exists to support behavior from earlier versions.

output_test_binary​

--[no-]go-test-output-test-binary
PANTS_GO_TEST_OUTPUT_TEST_BINARY
pants.toml
[go-test]
output_test_binary = <bool>
default: False

Write the test binary to the test extra output directory.

This is similar to the go test -c option, but will still run the underlying test.

Deprecated options​

None

None