go-unit-tests
Write or fix Go unit tests in this repo. Use when creating/editing *_test.go files, adding test coverage for Go code (usecases, repositories, services, handlers), or when the user asks to write, refac
SKILL.md.claude/skills/go-unit-tests/SKILL.md
GitHubGo Unit Tests
Authoritative style for unit tests in this codebase. Follow it exactly — these rules override generic Go testing habits. Existing test files may predate this style; when you touch a test, bring it into compliance.
When to use
- Writing tests for a new function/method/usecase/repository.
- Adding cases to existing tests or fixing failing tests.
- Reviewing test code for style compliance.
Non-negotiable rules
Structure
- Test package is
package <feature>_test(external test package), placed in the same directory as the code under test. - Follow the Uber Go Style Guide.
- One table-driven test per function under test. Use the subtest map below — never write sequential standalone assertions for variations of the same function.
- No conditional statements in tests — no
if,switch, or branching in the test body. Every case goes through the identical Arrange/Act/Assert path. If a case needs different behavior, encode it in the table, not in control flow.
Table format
The table is
map[string]struct{...}where the key is the test name.Test names are descriptive:
should ... when .../expects ... when .... e.g."should return ErrNotFound when movement does not exist".Group struct fields into three commented sections and predeclare named types for them:
type ( input struct { /* args passed to the function */ } expected struct { /* expectedOutput, expectedErr, ... */ } )The case struct holds:
// input,// mocks(amockSetupclosure),// expected.Always put expected values in the table (
expected.output,expected.err), never inline in the Assert section.
AAA pattern
- Mark every section with a comment:
// Arrange,// Act,// Assert. - Group multiple locals in Arrange with a single
var (...)block.
Mocks (testify/mock)
- Use
testify/mock. Define mocks inmock_test.goin the same package. - Before creating a mock, check whether it already exists (
mock_test.go,mocks.go, or amock.gonext to the interface) and reuse it. - Create mock instances with the address-of operator:
mockRepo := &MockRepo{}. - Do not use
mock.Anything. Match on the real expected argument values. - In the mock method, ignore
ctxwhen callingm.Called(...)— pass only the meaningful args:func (m *Mock) X(_ context.Context, id uuid.UUID) ... { args := m.Called(id); ... }. - Always call
mockX.AssertExpectations(t)(defer it right after constructing the mock).
Assertions (testify)
- Use
testify/assert. - Compare errors with
assert.ErrorIs(t, err, tc.expected.err)always — including the success case.errors.Is(nil, nil)is true, so a single uniform call covers both success and failure without anyif. Never writeassert.NoError/assert.Nil(err)/err == nil. - Use
assert.AnError(testify's sentinel) when a test needs an arbitrary error from a mock. - Naming:
expectedOutput,expectedErr, etc.
Canonical template
Copy this and adapt. It already encodes every rule above.
package usecase_test
import (
"context"
"testing"
"github.com/google/uuid"
"github.com/stretchr/testify/assert"
"personal-finance/internal/domain"
"personal-finance/internal/usecase"
)
// fixtureID is a shared test fixture (declare real fixtures in a fixture package).
var fixtureID = uuid.New()
func TestService_GetByID(t *testing.T) {
type (
input struct {
id uuid.UUID
}
expected struct {
output domain.Movement
err error
}
)
tests := map[string]struct {
// input
input input
// mocks
mockSetup func(mockRepo *MockMovementRepository)
// expected
expected expected
}{
"should return movement when it exists": {
input: input{id: fixtureID},
mockSetup: func(mockRepo *MockMovementRepository) {
mockRepo.On("FindByID", fixtureID).
Return(domain.Movement{ID: fixtureID}, nil)
},
expected: expected{
output: domain.Movement{ID: fixtureID},
err: nil,
},
},
"should return error when repository fails": {
input: input{id: fixtureID},
mockSetup: func(mockRepo *MockMovementRepository) {
mockRepo.On("FindByID", fixtureID).
Return(domain.Movement{}, assert.AnError)
},
expected: expected{
output: domain.Movement{},
err: assert.AnError,
},
},
}
for name, tc := range tests {
t.Run(name, func(t *testing.T) {
// Arrange
var (
mockRepo = &MockMovementRepository{}
svc = usecase.NewService(mockRepo)
)
defer mockRepo.AssertExpectations(t)
tc.mockSetup(mockRepo)
// Act
output, err := svc.GetByID(context.Background(), tc.input.id)
// Assert
assert.ErrorIs(t, err, tc.expected.err)
assert.Equal(t, tc.expected.output, output)
})
}
}
Mock template (mock_test.go)
package usecase_test
import (
"context"
"github.com/google/uuid"
"github.com/stretchr/testify/mock"
"personal-finance/internal/domain"
)
type MockMovementRepository struct {
mock.Mock
}
// ctx is ignored in m.Called.
func (m *MockMovementRepository) FindByID(_ context.Context, id uuid.UUID) (domain.Movement, error) {
args := m.Called(id)
return args.Get(0).(domain.Movement), args.Error(1)
}
Anti-patterns (reject these)
| Don't | Do |
|---|---|
if tc.expectedErr != nil { assert.Error(...) } |
assert.ErrorIs(t, err, tc.expected.err) (uniform, no if) |
assert.NoError(t, err) / err == nil |
assert.ErrorIs(t, err, tc.expected.err) with err: nil in table |
mockRepo.On("X", mock.Anything) |
match the real arg: mockRepo.On("X", fixtureID) |
m.Called(ctx, id) in the mock method |
m.Called(id) — ignore ctx |
errors.New("boom") for a throwaway error |
assert.AnError |
| New mock when one already exists | grep first, reuse |
| Slice-of-structs table | map[string]struct{...} keyed by name |
Run & verify
go test ./internal/path/to/package/... # single package
make test # full suite with race + coverage
Always run the relevant package's tests after writing them and confirm they pass before reporting done.