Testing Go

Testing Go

You test behavior at the package boundary, not private internals. A Go test that breaks because you renamed an unexported field was testing the wrong thing. Target Go 1.25 (released 2025-08-12) unless the module's go directive says otherwise — several APIs below only exist in recent versions.

Default stack, in order of reach:

1. The standard testing package. It is enough for ~90% of tests.
2. testify/require (and assert) only where stdlib comparisons get noisy — deep-equal on big structs, repeated if err != nil { t.Fatal }. Not as a reflex.
3. Hand-written fakes over any mock generator. A 12-line fake beats gomock for code you own.

Run go test ./... early and often. Add -race for anything that touches a goroutine. The test suite is your fastest feedback loop — keep it fast and deterministic so you actually run it.

What am I testing? Pick the tool

If you find yourself reaching past the standard library for the first row, stop — table-driven tests need nothing else.

Table-driven tests

The canonical shape: a slice of anonymous structs with a name, run as named subtests.

func TestReverse(t *testing.T) {
	tests := []struct {
		name string
		in   string
		want string
	}{
		{name: "empty", in: "", want: ""},
		{name: "ascii", in: "abc", want: "cba"},
		{name: "unicode", in: "héllo", want: "olléh"},
	}
	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			got := Reverse(tc.in)
			if got != tc.want {
				t.Errorf("Reverse(%q) = %q, want %q", tc.in, got, tc.want)
			}
		})
	}
}

• Name every case. t.Run(tc.name, ...) gives you go test -run TestReverse/unicode to target one case, and a readable failure path instead of "index 2".
• Use t.Errorf, not t.Fatalf, inside the loop unless the rest of the case is meaningless after the failure. Fatalf stops the whole subtest; Errorf lets the other cases still run.
• One table per behavior, not per function. If two functions share inputs and expectations, one table. If a case needs three extra fields only it uses, that case wants its own test.

Bad — copy-pasted near-identical functions:

func TestAddOne(t *testing.T)  { if Add(1) != 2 { t.Fail() } }
func TestAddTwo(t *testing.T)  { if Add(2) != 3 { t.Fail() } }
func TestAddZero(t *testing.T) { if Add(0) != 1 { t.Fail() } }

Good — one table, each case named, failures localized (see the TestReverse shape above).

Parallel & isolation

for _, tc := range tests {
	t.Run(tc.name, func(t *testing.T) {
		t.Parallel() // this subtest runs concurrently with its siblings
		got := Process(tc.in)
		if got != tc.want {
			t.Errorf("Process(%q) = %v, want %v", tc.in, got, tc.want)
		}
	})
}

• Do not write tc := tc before t.Run. Go 1.22+ gives each loop iteration its own variable scope, so the historical copy is dead ceremony. Only modules whose go.mod declares go 1.21 or older still need it — and you should bump the directive instead.
• t.Cleanup(fn) over defer for teardown that must run even when a helper calls t.Fatal. Cleanups run LIFO after the test, and they nest correctly through helpers where a defer in main would not.
• t.Helper() as the first line of any assertion helper, so failures point at the caller's line, not inside the helper.
• t.TempDir() for filesystem tests — auto-removed, unique per test, parallel-safe. Never hardcode /tmp/mytest.
• t.Context() (Go 1.24+) gives a context cancelled when the test and its cleanups finish — pass it to anything taking a context.Context instead of context.Background().
• t.Setenv and T.Chdir forbid t.Parallel(). They mutate process-global state; the test panics if you call them in a parallel test. Keep env/cwd-mutating tests serial.

Fakes over mocks

Define the interface where you consume it (the test's package), keep it tiny, and hand-roll a fake with func fields you set per test.

// Charger is what the service needs — declared at the consumer, not the vendor.
type Charger interface {
	Charge(ctx context.Context, cents int64) (string, error)
}

type fakeCharger struct {
	charge func(ctx context.Context, cents int64) (string, error)
}

func (f fakeCharger) Charge(ctx context.Context, cents int64) (string, error) {
	return f.charge(ctx, cents)
}

func TestCheckout_chargesOnce(t *testing.T) {
	var calls int
	f := fakeCharger{charge: func(_ context.Context, c int64) (string, error) {
		calls++
		return "txn_123", nil
	}}
	if err := Checkout(t.Context(), f, 999); err != nil {
		t.Fatalf("Checkout: %v", err)
	}
	if calls != 1 {
		t.Errorf("Charge called %d times, want 1", calls)
	}
}

This is faster to read than a generated mock and never couples your test to call order. Reach for go.uber.org/mock (gomock) or testify/mock only when a team already mandates them or the interface is large and call-sequence assertions are the point — templates and the decision in references/mocks-and-fakes.md. For HTTP dependencies use net/http/httptest (server, recorder, or a fake RoundTripper) instead of a fake — same reference.

Concurrency & time (synctest)

testing/synctest graduated to GA in Go 1.25. It runs your code in an isolated "bubble" with a fake clock that jumps forward instantly the moment every goroutine in the bubble is durably blocked — so a test of a 30-second timeout finishes in microseconds, deterministically.

func TestTimeout(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
		defer cancel()

		done := make(chan error, 1)
		go func() { done <- slowOperation(ctx) }()

		synctest.Wait() // wait until the goroutine is durably blocked
		select {
		case err := <-done:
			if !errors.Is(err, context.DeadlineExceeded) {
				t.Errorf("got %v, want DeadlineExceeded", err)
			}
		case <-time.After(time.Minute): // fake time — never really waits
			t.Fatal("operation did not time out")
		}
	})
}

• Always run concurrent code with -race (go test -race ./...). The race detector finds data races that pass silently otherwise.
• synctest.Wait() blocks the bubble until all other bubble goroutines are durably blocked, letting you assert at a known point.
• Use synctest.Test(t, ...), not the old synctest.Run — Run is deprecated as of Go 1.26.
• Never use time.Sleep to "let the goroutine finish." That is the flaky-test factory. Full bubble semantics, durable-block definition, and goroutine-leak detection live in references/synctest-and-concurrency.md.

Coverage

go test -cover ./...                                   # quick per-package %
go test -coverprofile=cover.out ./...                  # write a profile
go tool cover -html=cover.out                          # open annotated source
go test -coverpkg=./... -coverprofile=cover.out ./...  # cross-package coverage
go build -cover -o ./bin/app .                         # coverage for integration binaries (1.20+)

A coverage percentage is a smoke alarm, not a goal. 100% line coverage with no assertions on the values is worthless; 70% on the branches that actually carry logic is fine. Use -coverpkg=./... when your tests live in a separate package and exercise code across the module, or the number undercounts. Profiles, integration-binary coverage, and reading the HTML report are in references/coverage-and-benchmarks.md.