Testing in Go — Table-Driven Tests, Benchmarks, and go test Habits

Testing in Go — Table-Driven Tests, Benchmarks, and go test Habits

In part 5 I built a working Orders API with Gin — routes, middleware, an in-memory store, and proper error handling. This time I'm writing tests for it, and the story here is one of the things I've genuinely liked about Go from the start: testing is a first-class citizen with zero framework ceremony. No JUnit, no Mockito, no Spring Boot test context to spin up. Just go test and the standard library.

The go test Mental Model

Every _test.go file in a Go package is compiled and run by go test. Test functions follow one convention — they take a single *testing.T argument and start with Test:

func TestSomething(t *testing.T) {
    // ...
}

That's the entire contract. No annotations, no base classes, no test runner configuration file. Running go test ./... from the project root picks up every test across every package recursively. Running with -v shows each test name and its pass/fail. Running with -race enables the data race detector we talked about in part 3. These three invocations cover 90% of what I reach for day to day:

go test ./...                  # run everything
go test -v ./handler/...       # verbose, one package
go test -race ./...            # race detector on
go test -run TestCreateOrder . # run one test by name

Table-Driven Tests: The Go Idiom

The single most important testing pattern in Go is the table-driven test. Instead of writing one test function per scenario, you define a slice of cases as a struct, loop over them, and let the test framework tell you exactly which case failed. Coming from JUnit's @ParameterizedTest, it's the same idea — except it's just a for loop, no framework required:

// store/order_test.go
package store_test

import (
    "testing"

    "orders-api/model"
    "orders-api/store"
)

func TestCreateOrder(t *testing.T) {
    cases := []struct {
        name      string
        input     model.CreateOrderRequest
        wantErr   bool
    }{
        {
            name:    "valid order",
            input:   model.CreateOrderRequest{Customer: "Alice", Amount: 99.99},
            wantErr: false,
        },
        {
            name:    "zero amount",
            input:   model.CreateOrderRequest{Customer: "Bob", Amount: 0},
            wantErr: false, // store doesn't validate, handler does
        },
        {
            name:    "empty customer",
            input:   model.CreateOrderRequest{Customer: "", Amount: 50.0},
            wantErr: false,
        },
    }

    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            s := store.NewInMemoryStore()
            order, err := s.Create(tc.input)

            if tc.wantErr && err == nil {
                t.Errorf("expected error, got nil")
            }
            if !tc.wantErr && err != nil {
                t.Errorf("unexpected error: %v", err)
            }
            if !tc.wantErr && order.ID == "" {
                t.Errorf("expected non-empty order ID, got empty string")
            }
        })
    }
}

t.Run creates a named sub-test for each case. When a sub-test fails, Go prints the full path — TestCreateOrder/zero_amount — so you know instantly which case broke without digging through output. This is the pattern the entire Go standard library uses internally, and it's the first habit worth locking in.

Testing the Store: ErrNotFound

The GetByID path needs its own table — specifically the not-found branch we wired into the handler in part 5:

func TestGetByID(t *testing.T) {
    s := store.NewInMemoryStore()

    // seed one order
    created, _ := s.Create(model.CreateOrderRequest{
        Customer: "Alice",
        Amount:   49.99,
    })

    cases := []struct {
        name    string
        id      string
        wantErr error
    }{
        {"existing order", created.ID, nil},
        {"missing order", "does-not-exist", store.ErrNotFound},
        {"empty id", "", store.ErrNotFound},
    }

    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            _, err := s.GetByID(tc.id)
            if !errors.Is(err, tc.wantErr) {
                t.Errorf("got err %v, want %v", err, tc.wantErr)
            }
        })
    }
}

errors.Is in the test assertion mirrors exactly how the handler checks errors — the sentinel defined in the store package is the contract, and we're verifying both sides of it honour it.

Handler Tests with httptest

Testing the handler layer without spinning up a real server is where Go's net/http/httptest package earns its place. It gives you a fake ResponseRecorder that captures everything the handler writes — status code, headers, body — without any network involvement:

// handler/order_test.go
package handler_test

import (
    "bytes"
    "encoding/json"
    "net/http"
    "net/http/httptest"
    "testing"

    "orders-api/handler"
    "orders-api/model"
    "orders-api/store"

    "github.com/gin-gonic/gin"
)

func setupRouter(h *handler.OrderHandler) *gin.Engine {
    gin.SetMode(gin.TestMode)
    r := gin.New()
    r.POST("/orders", h.Create)
    r.GET("/orders/:id", h.GetByID)
    r.GET("/orders", h.List)
    return r
}

func TestCreateOrderHandler(t *testing.T) {
    cases := []struct {
        name       string
        body       any
        wantStatus int
    }{
        {
            name:       "valid request",
            body:       model.CreateOrderRequest{Customer: "Alice", Amount: 99.99},
            wantStatus: http.StatusCreated,
        },
        {
            name:       "missing customer",
            body:       map[string]any{"amount": 49.99},
            wantStatus: http.StatusBadRequest,
        },
        {
            name:       "negative amount",
            body:       map[string]any{"customer": "Bob", "amount": -10},
            wantStatus: http.StatusBadRequest,
        },
    }

    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            s := store.NewInMemoryStore()
            h := handler.NewOrderHandler(s)
            r := setupRouter(h)

            bodyBytes, _ := json.Marshal(tc.body)
            req := httptest.NewRequest(http.MethodPost, "/orders", bytes.NewReader(bodyBytes))
            req.Header.Set("Content-Type", "application/json")
            w := httptest.NewRecorder()

            r.ServeHTTP(w, req)

            if w.Code != tc.wantStatus {
                t.Errorf("status: got %d, want %d — body: %s",
                    w.Code, tc.wantStatus, w.Body.String())
            }
        })
    }
}

gin.SetMode(gin.TestMode) suppresses the debug output Gin prints during tests. Each case builds a fresh store and handler so tests are fully isolated — no shared state leaking between cases. The w.Body.String() in the error message means a failing test prints the actual response body, which cuts debug time significantly.

Benchmarks: Built Right In

Benchmarks follow the same file and naming conventions as tests, but use *testing.B and prefix with Benchmark. The runner calls your function repeatedly, adjusting iteration count until the timing is stable:

func BenchmarkStoreList(b *testing.B) {
    s := store.NewInMemoryStore()

    // seed 1000 orders
    for i := 0; i < 1000; i++ {
        s.Create(model.CreateOrderRequest{
            Customer: fmt.Sprintf("customer-%d", i),
            Amount:   float64(i) * 1.5,
        })
    }

    b.ResetTimer() // don't count seeding time

    for i := 0; i < b.N; i++ {
        _, err := s.List()
        if err != nil {
            b.Fatal(err)
        }
    }
}

Running go test -bench=. -benchmem ./store/... gives you nanoseconds per operation and allocations per operation:

BenchmarkStoreList-8    42361    28204 ns/op    24576 B/op    3 allocs/op

b.ResetTimer() after the seeding step is the habit that matters most here — you want to measure List, not Create × 1000. The -benchmem flag surfacing allocations per operation is the other one: in a hot path, allocation count matters as much as raw speed.

The go test Habits Worth Locking In

After a few weeks of writing Go tests, these are the ones I've made automatic:

Always use t.Run for multi-case scenarios. Even two cases. The named sub-test output pays for the extra line immediately when something breaks.

t.Parallel() for independent tests. Adding t.Parallel() at the top of a test (or sub-test) tells the runner it can execute concurrently with other parallel tests, cutting total test time on multi-core machines with no other changes.

-race in CI, always. Data races in Go are silent in normal test runs and catastrophic in production. The race detector adds overhead but catches things that would otherwise survive code review and only surface under load.

testify/assert if your team agrees, testing if they don't. The standard testing package requires writing your own error messages for every assertion. testify/assert gives you assert.Equal, assert.NoError, and friends with good default messages. Both are valid choices — the important thing is consistency within a codebase.

Up Next

Part 7 is the finish line: multi-stage Docker build, graceful shutdown, and getting this service onto ECS Fargate — the same deployment target I used for rust-ai-gateway. The testing patterns from this post will feed directly into the CI pipeline we wire up there.

Do you have a preferred Go testing library — pure testing, testify, or something else? Curious whether the standard library alone is enough once the projects get bigger.