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

GitHub

Go 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 (a mockSetup closure), // 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 in mock_test.go in the same package.
  • Before creating a mock, check whether it already exists (mock_test.go, mocks.go, or a mock.go next 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 ctx when calling m.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 any if. Never write assert.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.