go test, list & generate

go test runs package tests, go list introspects what the build system sees, and go generate triggers code generation hooks you define beside source files.

Summary

Testing is first-class in the toolchain: no external runner is required for unit tests, benchmarks, examples, or fuzz targets.

go list exposes packages, dependencies, tags, and module versions as machine-readable JSON for scripts and CI.

go generate runs //go:generate directives, usually shelling out to tools installed with go install.

Together they form the daily loop: list what exists, generate what is stale, test what changed.

Recipe

Quick-reference recipe card - copy-paste ready.

# Run all tests with race detector and coverage
go test -race -cover ./...
 
# Run one test by name with verbose output
go test -run TestParseConfig -v ./internal/config
 
# List packages as JSON for scripting
go list -json ./...
 
# Run all generators in the module
go generate ./...

When to reach for this:

• Use go test ./... as the default CI gate before merge.
• Use go list -f templates to build SBOM or ownership reports.
• Use go generate after changing protobuf, stringer, or mock definitions.
• Use go test -bench when optimizing hot paths with reproducible numbers.

Working Example

// mathutil/sum.go
package mathutil
 
func Sum(nums []int) int {
    total := 0
    for _, n := range nums {
        total += n
    }
    return total
}

// mathutil/sum_test.go
package mathutil
 
import "testing"
 
func TestSum(t *testing.T) {
    got := Sum([]int{1, 2, 3})
    if got != 6 {
        t.Fatalf("got %d want 6", got)
    }
}
 
func BenchmarkSum(b *testing.B) {
    data := make([]int, 1000)
    for i := range data {
        data[i] = i
    }
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        Sum(data)
    }
}

// api/doc.go
package api
 
//go:generate go run golang.org/x/tools/cmd/stringer@latest -type=Kind
 
type Kind int
 
const (
    KindHTTP Kind = iota
    KindGRPC
)

go test -cover ./mathutil
go test -bench=. -benchmem ./mathutil
go list -f '{{.ImportPath}} tags={{.BuildTags}}' ./...
go generate ./api

What this demonstrates:

• Table-free unit test with t.Fatalf for fast failure.
• Benchmark with b.ResetTimer() excluding setup work.
• go list -f custom template for inventory scripts.
• //go:generate colocated with the type it maintains.

Deep Dive

How It Works

• go test compiles a test main that links _test.go files, then executes the binary and streams results.
• Test cache keys include source hashes, flags, and Go version; passing results reuse unless -count=1.
• go list loads packages without necessarily linking; -json emits structs for automation.
• go generate scans for //go:generate lines and runs commands in file order; it does not track staleness itself.

go test Flags at a Glance

go list Templates

go generate Rules

• Directives must start with //go:generate (no space before go).
• Commands run with the package directory as working directory.
• Generators should be idempotent; commit outputs or enforce git diff checks in CI.
• Prefer go run tool@version over undocumented local binaries for reproducibility.

Gotchas

• Assuming go test without ./... runs everything - bare . is only the current package. Fix: go test ./... from module root.
• Flaky pass cached forever - default cache hides intermittent failures. Fix: go test -count=1 while debugging; fix root cause before merging.
• Benchmarking without -benchmem - allocation regressions stay invisible. Fix: add -benchmem and compare with benchstat.
• go generate in CI without checking diffs - drift merges silently. Fix: run generate in a job that fails on non-empty git diff.
• External test package confusion - package foo_test cannot access unexported symbols. Fix: test exported API or use internal test package package foo.
• List JSON parsing by hand - easy to miss embedded newlines. Fix: use jq on go list -json output in scripts.

Alternatives

FAQs

Related

• The go Command: Build, Test, and Module Lifecycle - shared loader pipeline
• Go Toolchain Basics - first go test and go list examples
• go fix Modernizers & go vet Analyzers - static checks before tests
• Build Tags & Conditional Compilation - why list output differs by tags
• Go Toolchain Best Practices - CI testing habits

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).