go-test-quality

Go Test Quality

Tests are production code. They run in CI on every commit, they document behavior, and they're the first thing you read when a function breaks at 3am. Write them with the same care you'd give to code that handles money.

Detailed reference material, loaded on demand:

• references/helpers-and-fixtures.md — test helpers, factory functions with options, t.Cleanup, golden files, mock implementations.
• references/integration-testing.md — httptest recorder and server, testcontainers, build tags, TestMain, fuzz testing.

Read a reference file only when the summary below is not enough.

1. Test Design Philosophy

Test behavior, not implementation

// ✅ Good — tests what the function DOES
func TestTransferFunds_InsufficientBalance(t *testing.T) {
    from := NewAccount("alice", 100)
    to := NewAccount("bob", 0)

    err := TransferFunds(from, to, 150)

    require.ErrorIs(t, err, ErrInsufficientFunds)
    assert.Equal(t, 100, from.Balance(), "sender balance should be unchanged")
    assert.Equal(t, 0, to.Balance(), "receiver balance should be unchanged")
}

// ❌ Bad — tests HOW the function does it
// asserts debit() was called before credit(), rollback() was called,
// internal mutex was locked — breaks on every refactor

One assertion per logical concept

Multiple assert calls are fine when they verify different facets of the SAME behavior (both accounts after a transfer). A test that checks creation AND update AND deletion is three tests pretending to be one.

Name tests like bug reports

When the test fails, the name alone should say what broke:

// ✅ Good — reads like a sentence
func TestOrderService_Cancel_RefundsPartiallyShippedItems(t *testing.T) { ... }
func TestParseConfig_ReturnsErrorOnMissingRequiredField(t *testing.T) { ... }

// ❌ Bad — says nothing useful
func TestCancel(t *testing.T) { ... }
func TestRateLimiter_Success(t *testing.T) { ... }

2. Subtests for Organized Scenarios

Use t.Run to group related scenarios under a parent test. Each subtest gets its own setup, its own failure, and its own name in CI output: