Go Testing Best Practices

By Robert F4 min readFebruary 22, 2026

Structuring Tests

A well-structured test suite is essential for clarity and maintainability. Tests in Go are typically organized in the same package as the code being tested, but in a separate file that ends with _test.go. This allows for easy access to unexported functions and types.

Example Directory Structure

/myapp
    ├── main.go
    ├── main_test.go
    └── utils
        ├── utils.go
        └── utils_test.go

Naming Conventions

Test functions should begin with Test followed by the name of the function being tested. This convention ensures that the Go testing tool can automatically discover the tests.

// main_test.go
package main

import "testing"

func TestAdd(t *testing.T) {
    result := Add(2, 3)
    expected := 5
    if result != expected {
        t.Errorf("expected %d, got %d", expected, result)
    }
}

Table-Driven Tests

Table-driven tests are a powerful pattern in Go that allows you to define multiple test cases in a single test function. This approach reduces code duplication and enhances readability.

Example of Table-Driven Tests

// utils/utils.go
package utils

func Add(a, b int) int {
    return a + b
}

// utils/utils_test.go
package utils

import "testing"

func TestAdd(t *testing.T) {
    tests := []struct {
        a, b     int
        expected int
    }{
        {1, 2, 3},
        {2, 3, 5},
        {5, 5, 10},
        {-1, 1, 0},
    }

    for _, test := range tests {
        result := Add(test.a, test.b)
        if result != test.expected {
            t.Errorf("Add(%d, %d) = %d; expected %d", test.a, test.b, result, test.expected)
        }
    }
}

Benefits of Table-Driven Tests

Benefit	Description
Clarity	Each test case is clearly defined in a structured manner.
Reduced Duplication	Common setup code is minimized.
Easy to Extend	Adding new test cases is straightforward.

Using Mocks for Dependencies

When testing functions that depend on external services (like databases or APIs), it’s essential to isolate these dependencies. Mocking allows you to simulate external services, making your tests faster and more reliable.

Example of Mocking

Consider a function that fetches user data from a database:

// user.go
package user

type User struct {
    ID   int
    Name string
}

type UserRepository interface {
    GetUser(id int) (User, error)
}

func GetUserName(repo UserRepository, id int) (string, error) {
    user, err := repo.GetUser(id)
    if err != nil {
        return "", err
    }
    return user.Name, nil
}

You can create a mock implementation of UserRepository for testing:

// user_test.go
package user

import (
    "errors"
    "testing"
)

type mockUserRepository struct {
    users map[int]User
}

func (m *mockUserRepository) GetUser(id int) (User, error) {
    user, exists := m.users[id]
    if !exists {
        return User{}, errors.New("user not found")
    }
    return user, nil
}

func TestGetUserName(t *testing.T) {
    repo := &mockUserRepository{
        users: map[int]User{
            1: {ID: 1, Name: "Alice"},
            2: {ID: 2, Name: "Bob"},
        },
    }

    name, err := GetUserName(repo, 1)
    if err != nil || name != "Alice" {
        t.Errorf("expected Alice, got %s", name)
    }

    _, err = GetUserName(repo, 3)
    if err == nil {
        t.Error("expected error for non-existent user")
    }
}

Testing for Race Conditions

When dealing with concurrency, it is essential to test for race conditions. Go provides a built-in race detector that can be enabled during testing.

Running Tests with Race Detector

You can run your tests with the race detector using the following command:

go test -race ./...

This command will help identify any race conditions in your code, allowing you to address them before they cause issues in production.

Summary of Best Practices

Best Practice	Description
Structure Tests Properly	Use `_test.go` files and follow naming conventions.
Use Table-Driven Tests	Define multiple test cases in a single function.
Mock External Dependencies	Isolate tests from external services using mocks.
Test for Race Conditions	Utilize Go's race detector to identify concurrency issues.

By following these best practices, you can ensure that your Go tests are effective, maintainable, and robust, leading to higher code quality and fewer bugs in production.