Testing

Your first test

A test lives next to the code it checks, in a file ending _test.go, and is any function shaped func TestXxx(t *testing.T). Here’s a tiny function and its test:

// math.go
package math

func Abs(x int) int {
	if x < 0 {
		return -x
	}
	return x
}

// math_test.go
package math

import "testing"

func TestAbs(t *testing.T) {
	got := Abs(-3)
	want := 3
	if got != want {
		t.Errorf("Abs(-3) = %d, want %d", got, want)
	}
}

The got / want naming is a strong Go convention — it makes failure messages read like a sentence: got 5, want 3. You can run the real logic here in main to see it execute:

package main

import "fmt"

// Abs is the function under test.
func Abs(x int) int {
if x < 0 {
	return -x
}
return x
}

func main() {
for _, x := range []int{-3, 0, 7} {
	fmt.Printf("Abs(%d) = %d\n", x, Abs(x))
}
}

Errorf vs Fatalf, and t.Helper

t.Errorf marks the test failed but keeps running — good for independent checks so you see them all at once. t.Fatalf marks it failed and stops the test function — use it when continuing would crash or is pointless (a nil you’d dereference, an err that means nothing else is valid):

func TestParse(t *testing.T) {
	v, err := Parse("12")
	if err != nil {
		t.Fatalf("Parse returned error: %v", err) // stop: v is unusable
	}
	if v != 12 {
		t.Errorf("Parse = %d, want 12", v)        // keep going
	}
}

When you extract a repeated assertion into a helper, call t.Helper() first so failures point at the caller’s line, not at the helper’s internals:

func assertEqual(t *testing.T, got, want int) {
	t.Helper() // failures are reported at the line that called assertEqual
	if got != want {
		t.Errorf("got %d, want %d", got, want)
	}
}

graph TD
A["go test ./..."] --> B["compile *_test.go with package"]
B --> C["find every TestXxx(t *testing.T)"]
C --> D["run each test"]
D --> E{"t.Errorf called?"}
E -->|"no"| F["PASS"]
E -->|"yes / t.Fatalf"| G["FAIL: print got vs want"]

Running tests

go test builds and runs the tests in the current package. The flags you’ll reach for daily:

# run tests in this package
$ go test
ok      example/math    0.002s

# run tests in every package under the module
$ go test ./...

# -v prints each test name and PASS/FAIL
$ go test -v
=== RUN   TestAbs
--- PASS: TestAbs (0.00s)
PASS
ok      example/math    0.003s

# -run filters by regexp on the test name
$ go test -run TestAbs -v

A failing run shows the file, line, and your message:

$ go test
--- FAIL: TestAbs (0.00s)
    math_test.go:8: Abs(-3) = -3, want 3
FAIL
exit status 1
FAIL    example/math    0.002s

Setup, cleanup, and temp dirs

Tests that touch files, databases, or servers need setup and teardown. Two testing features make this clean and leak-free. t.Cleanup(fn) registers teardown that runs when the test (and its subtests) finish — in LIFO order, even after a t.Fatal. Unlike a defer in the test body, it can be registered inside a helper, so a helper owns both ends of a resource. t.TempDir() hands you a fresh directory that’s deleted automatically:

func TestWritesFile(t *testing.T) {
	dir := t.TempDir() // unique; auto-removed when the test ends
	path := filepath.Join(dir, "out.txt")

	if err := Save(path, "data"); err != nil {
		t.Fatalf("Save: %v", err)
	}
	got, _ := os.ReadFile(path)
	if string(got) != "data" {
		t.Errorf("file = %q, want %q", got, "data")
	}
}

// A helper that owns its own teardown via t.Cleanup.
func newTestServer(t *testing.T) *Server {
	t.Helper()
	s := startServer()
	t.Cleanup(s.Stop) // runs automatically at test end
	return s
}

Related controls: t.Skip/t.Skipf bail out of a test that can’t run here (e.g. if testing.Short() { t.Skip(...) } under go test -short); t.Setenv sets an env var for the duration of the test; and a package-level TestMain(m *testing.M) wraps one-time setup/teardown around the whole package’s run (os.Exit(m.Run())).

The t toolbox

Run with the race detector during development — go test -race ./... — to catch concurrency bugs the assertions alone won’t (see the race detector).

See also

• table-driven tests & subtests — scale one test to dozens of cases with t.Run.
• benchmarks — func BenchmarkXxx(b *testing.B) for performance.
• fuzzing — let the toolchain generate inputs you didn’t think of.
• the race detector — go test -race to surface data races.

Next: scaling one test into many cases — table-driven tests & subtests.

Related topics