go-test

Test the package found in the current directory

$ go test

$ go test -v

$ go test -v ./...

$ go test -v -bench .

$ go test -v -bench . -benchtime [50s]

$ go test -cover

go test [build flags] [packages] [test flags]

build flags: These flags control how the test binary is built, e.g., -mod=vendor to use vendored modules.
packages: Specifies the packages to test. Examples: . (current package), ./... (current package and all subpackages), or specific package paths like github.com/my/pkg. If omitted, the current directory's package is tested.
test flags: These flags control the execution of the test binary itself, e.g., -v for verbose output.

-v
    Verbose output: print the names of test functions as they are executed and report test failures in full.

-run
    Run only those tests and examples whose names match the regular expression. This flag applies to TestXxx and ExampleXxx functions.

-count
    Run each test and benchmark n times. If n=0, no caching is used.

-cover
    Enable code coverage analysis. When set, go test will print a summary of the code coverage.

-coverprofile
    Write a coverage profile to the specified file. This file can then be used with go tool cover to generate reports.

-race
    Enable data race detection. When a data race is detected, go test will report it.

-bench
    Run benchmarks matching the regular expression. This flag applies to BenchmarkXxx functions.

-benchtime
    Run each benchmark for a duration (e.g., 1s, 100ms). Default is 1s.

-cpu
    Comma-separated list of GOMAXPROCS values for which to run benchmarks. (e.g., 1,2,4).

-json
    (Go 1.15+) Output test results in JSON format, suitable for machine parsing. This replaces the default textual output.

-args
    Pass all subsequent arguments directly to the test binary, after which go test processing ceases. Useful for custom test arguments.

-timeout
    Fail a test if it takes longer than the specified duration (e.g., 30s, 2m).

-short
    Instructs tests to run in 'short' mode. Tests can use testing.Short() to skip long-running parts.

-parallel
    Run at most n test functions in parallel. By default, n is set to GOMAXPROCS.

The go test command automates the execution of tests for Go packages.

It works by compiling the source files of a package, along with any files named _test.go that contain test functions, benchmark functions, and example functions. The compiled test binary is then executed. Functions named TestXxx (where Xxx is an alphanumeric string starting with an uppercase letter) are considered test functions. Similarly, BenchmarkXxx are benchmark functions and ExampleXxx are example functions.

go test provides a comprehensive framework for unit, integration, and performance testing, seamlessly integrated into the Go toolchain. It can also generate code coverage reports and detect data races.

Requires Go Environment: A Go development environment (Go SDK) must be installed and configured.
File Naming: Test source files must adhere to the Go convention of ending with _test.go.
Function Naming: Test, Benchmark, and Example functions must start with an uppercase letter and reside in _test.go files.
Performance Impact: Running tests with race detection (-race) or extensive coverage analysis (-cover) can significantly increase test execution time and memory usage.
Flag Scope: Flags like -v, -run, -bench are passed to the compiled test binary, not directly interpreted by the go test command itself.

Go test files must always end with the suffix _test.go. For example, tests for mypackage.go would typically be in mypackage_test.go.

Test functions must have the signature func TestXxx(t *testing.T). Benchmark functions must have func BenchmarkXxx(b *testing.B). Example functions must have func ExampleXxx() or func ExampleXxx_suffix() and optionally print output to standard output.

go test is an integral part of the standard Go toolchain, meaning it's available out-of-the-box with any Go installation without requiring additional setup or external dependencies for basic testing.

The go test command and the testing package have been fundamental components of the Go programming language since its early development. Go's creators aimed to provide a robust, built-in testing framework to encourage good testing practices from the outset. This native support eliminates the need for third-party test runners or complex configurations. Over time, go test has evolved with new features like integrated race detection, code coverage, and the ability to output results in JSON format (Go 1.15+), continuously enhancing its utility for Go developers.

go build(1), go run(1), go get(1), go install(1), go fmt(1)