Comprehensive Guide to Writing Tests in Go: Unit, Benchmark, Example, and Fuzz Testing

Testing is a crucial part of software development, and Go provides a built-in testing framework to facilitate writing various types of tests. This guide explains how to write test code in Go, covering four main test categories: unit tests, benchmark tests, example tests, and fuzz tests.

Test Classification

In Go, test cases can be classified as:

Unit tests: functions starting with Test (e.g., TestXxx or Test_Xxx ).

Benchmark tests: functions starting with Benchmark .

Example tests: functions starting with Example to test standard output.

Fuzz tests: functions starting with Fuzz (available since Go 1.18) for random input testing.

All these tests can be run with the go test command.

Testing Conventions

Test file naming : Test files must end with _test.go . For example, hello.go has a corresponding test file hello_test.go .

Package naming : Tests can be white‑box (same package) or black‑box (different package). White‑box tests can access unexported identifiers, while black‑box tests can only use exported symbols.

Test function naming : Test functions must start with Test , Benchmark , Example , or Fuzz . The function signature varies:

func TestXxx(t *testing.T) { ... }
func BenchmarkXxx(b *testing.B) { ... }
func ExampleXxx() { ... }
func FuzzXxx(f *testing.F) { ... }

Variable naming conventions such as got/want or actual/expected are commonly used.

Unit Tests

Example of a simple unit test for an Abs function:

package abs
import "testing"
func TestAbs(t *testing.T) {
    got := Abs(-1)
    if got != 1 {
        t.Errorf("Abs(-1) = %f; want 1", got)
    }
}

Table‑driven tests improve readability and coverage:

func TestAbs_TableDriven(t *testing.T) {
    tests := []struct {
        name string
        x    float64
        want float64
    }{{name: "positive", x: 2, want: 2}, {name: "negative", x: -3, want: 3}}
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            if got := Abs(tt.x); got != tt.want {
                t.Errorf("Abs(%f) = %v, want %v", tt.x, got, tt.want)
            }
        })
    }
}

Tests can be run in parallel using t.Parallel() and can be skipped in CI environments with t.Skip() .

Benchmark Tests

Benchmark tests measure performance. Example:

func BenchmarkAbs(b *testing.B) {
    for i := 0; i < b.N; i++ {
        Abs(-1)
    }
}

Run benchmarks with go test -bench=. . Flags like -benchmem , -benchtime , and -cpu provide memory statistics, execution time control, and parallelism settings.

Example Tests

Example tests verify standard output and are recognized by documentation tools:

func ExampleAbs() {
    fmt.Println(Abs(-1))
    fmt.Println(Abs(2))
    // Output:
    // 1
    // 2
}

Unordered output can be checked with // Unordered Output: . These examples are displayed by pkgsite and godoc .

Fuzz Tests

Fuzz testing generates random inputs to discover edge‑case bugs. Example for a Hello function:

func FuzzHello(f *testing.F) {
    f.Add("Foo")
    f.Fuzz(func(t *testing.T, name string) {
        _, err := Hello(name)
        if err != nil && !errors.Is(err, ErrEmptyName) && !errors.Is(err, ErrTooLongName) {
            t.Errorf("unexpected error: %s, name: %s", err, name)
        }
    })
}

Run with go test -fuzz=FuzzHello . The tool generates seed files under testdata/fuzz and reports failing inputs.

Test Coverage

Use go test -cover to view coverage percentages, or generate a profile with -coverprofile=coverage.out and visualize it via go tool cover -html=coverage.out . Coverage helps ensure that unit, example, and fuzz tests are exercised, while benchmarks require explicit inclusion.

Conclusion

The article demonstrates how to write and run unit, benchmark, example, and fuzz tests in Go, emphasizing best practices such as table‑driven tests, parallel execution, coverage measurement, and integration into CI pipelines.