5.2Моки и интеграционные тесты

Выберем подходящий test double для границы и отделим проверку поведения от проверки взаимодействия.

Подделки зависимостей: стаб, мок, спай, фейк

Тестируемый код лезет в базу, в платёжный шлюз и в Kafka. Что подставить вместо них, чтобы тест был быстрым и повторяемым? Подставляют «подделку», а подделки бывают пяти сортов. В повседневной речи их все зовут «моками», но на собесе разницу спрашивают почти всегда, потому что за ней стоит выбор: подставить данные или проверить факт вызова.

1. Test double - общее слово для любой подделки

Test double значит «тестовый дублёр», по аналогии с каскадёром, который заменяет актёра в опасной сцене. Термин зонтичный: так зовут любой объект, который подставили вместо настоящей зависимости на время теста. Четыре слова ниже называют его разновидности; классификацию придумал Джерард Месарош, и спрашивают обычно именно её.

2. Стаб - отвечает заранее заготовленным, ничего не проверяет

Стаб (stub - «заглушка», «корешок») нужен, чтобы поставить систему в нужное состояние. Ты заранее говоришь: «на Get(42) верни вот этот заказ», или «верни ошибку 503». Стаб просто отдаёт это, и всё. Провалить тест он не может, решение принимает проверка в конце теста. Самый частый и самый безобидный дублёр.

3. Мок - заранее объявленные ожидания, проваливает тест сам

Мок (mock, «имитация», «пародия») добавляет к стабу ожидания, записанные до вызова: «метод Charge должен быть вызван ровно один раз, с суммой 500». Если вызвали не так, не столько раз или не в том порядке, мок роняет тест сам, без единого ассерта в коде теста. Отсюда и его польза, и его беда: тест начинает знать, как код устроен внутри, и ломается на любом рефакторинге, даже если поведение не изменилось.

4. Спай - стаб, который ещё и ведёт журнал вызовов

Спай (spy, «шпион») стоит посередине между стабом и моком. Он отвечает как стаб, но попутно записывает в слайс, кто его звал и с какими аргументами. Проверяют это потом, обычной строчкой в теле теста: if len(s.calls) != 1 { ... }. От мока спай отличается тем, где живёт проверка: у спая - в тесте и после факта, у мока - внутри библиотеки и заранее.

5. Фейк - упрощённая, но по-настоящему работающая реализация

Фейк (fake - «подделка», в смысле «копия, которая работает») стоит особняком: это не заглушка, а настоящая реализация интерфейса, только простая. Репозиторий на map[int]Order с мьютексом вместо PostgreSQL, очередь в памяти вместо Kafka, каталог на диске вместо S3. У фейка есть своё состояние: положил - прочитал, как в бою. Поэтому тест на фейке проверяет результат, а не последовательность вызовов, и рефакторинг его не ломает.

Точка подмены: интерфейс объявляется у потребителя

В Java или C# нормально написать UserRepository и рядом UserRepositoryImpl: интерфейс живёт вместе с реализацией. В Go так делать не принято, и дело не во вкусе, а в неявной реализации интерфейсов. Типу не надо писать implements: он подходит под интерфейс, если у него есть нужные методы. Значит, интерфейс можно объявить там, где он нужен, и никого не трогать.

Формулировки две: «The bigger the interface, the weaker the abstraction» из Go Proverbs Роба Пайка и «Accept interfaces, return structs» - правило, которое популяризовало сообщество. Отсюда правило:

Полный пример: сервис + репозиторий + клиент + тест

Через всю главу пройдёт один пример, сервис оформления заказа. Он читает заказ из БД, дёргает внешний платёжный API и сохраняет результат. Обе зависимости спрятаны за интерфейсами, объявленными в пакете order.

// ---------- internal/order/service.go ----------
package order

import (
    "context"
    "errors"
    "fmt"
)

var ErrNotFound = errors.New("order: не найден")

type Order struct {
    ID     int
    UserID int
    Amount int64
    Status string
}

// Интерфейсы объявлены здесь, у потребителя, и в них ровно то, чем пользуется сервис.
type Repo interface {
    Get(ctx context.Context, id int) (Order, error)
    UpdateStatus(ctx context.Context, id int, status string) error
}

type Payments interface {
    Charge(ctx context.Context, userID int, amount int64) (txID string, err error)
}

type Service struct {
    repo Repo
    pay  Payments
}

// Конструктор принимает интерфейсы и возвращает структуру: accept interfaces, return structs.
func NewService(r Repo, p Payments) *Service {
    return &Service{repo: r, pay: p}
}

func (s *Service) Pay(ctx context.Context, id int) (string, error) {
    o, err := s.repo.Get(ctx, id)
    if err != nil {
        return "", fmt.Errorf("получить заказ %d: %w", id, err)
    }
    if o.Status == "paid" {
        return "", errors.New("order: заказ уже оплачен")   // идемпотентность
    }
    if o.Amount <= 0 {
        return "", errors.New("order: некорректная сумма")
    }

    txID, err := s.pay.Charge(ctx, o.UserID, o.Amount)
    if err != nil {
        return "", fmt.Errorf("списание по заказу %d: %w", id, err)
    }
    if err := s.repo.UpdateStatus(ctx, id, "paid"); err != nil {
        // Деньги списаны, а статус не обновлён: ради этого кейса тест и пишут.
        return txID, fmt.Errorf("обновить статус %d (списание %s прошло): %w", id, txID, err)
    }
    return txID, nil
}

// ---------- internal/postgres/order_repo.go ----------
package postgres

// Никакого import "internal/order" ради интерфейса: пакет про него не знает.
// Он просто возвращает структуру, которая случайно подходит под order.Repo.
// Querier - общее у *sql.DB и *sql.Tx: в интеграционном тесте сюда придёт транзакция.
type Querier interface {
    QueryRowContext(ctx context.Context, q string, args ...any) *sql.Row
    ExecContext(ctx context.Context, q string, args ...any) (sql.Result, error)
}

type OrderRepo struct {
    db Querier
}

func NewOrderRepo(db Querier) *OrderRepo { return &OrderRepo{db: db} }

func (r *OrderRepo) Get(ctx context.Context, id int) (order.Order, error) { /* SQL */ }
func (r *OrderRepo) UpdateStatus(ctx context.Context, id int, status string) error { /* SQL */ }

Теперь тест. Он написан на «ручных» дублёрах, без единой библиотеки: так видно, что моки собираются из обычных структур с полями-функциями и никакой магии в них нет.

// ---------- internal/order/service_test.go ----------
package order_test

// stubRepo: подставляет данные, поведение задаётся полями-функциями.
type stubRepo struct {
    getFn    func(ctx context.Context, id int) (order.Order, error)
    updateFn func(ctx context.Context, id int, status string) error

    updateCalls []string          // а это уже spy: записываем, что с нами делали
}

func (s *stubRepo) Get(ctx context.Context, id int) (order.Order, error) {
    return s.getFn(ctx, id)
}
func (s *stubRepo) UpdateStatus(ctx context.Context, id int, status string) error {
    s.updateCalls = append(s.updateCalls, status)
    if s.updateFn == nil {
        return nil
    }
    return s.updateFn(ctx, id, status)
}

type stubPayments struct {
    txID string
    err  error
    gotAmount int64
}

func (s *stubPayments) Charge(ctx context.Context, userID int, amount int64) (string, error) {
    s.gotAmount = amount
    return s.txID, s.err
}

func TestService_Pay(t *testing.T) {
    t.Parallel()

    okOrder := order.Order{ID: 1, UserID: 7, Amount: 500, Status: "new"}

    t.Run("успешная оплата", func(t *testing.T) {
        t.Parallel()
        repo := &stubRepo{getFn: func(context.Context, int) (order.Order, error) { return okOrder, nil }}
        pay := &stubPayments{txID: "tx-42"}

        got, err := order.NewService(repo, pay).Pay(context.Background(), 1)

        require.NoError(t, err)
        require.Equal(t, "tx-42", got)
        require.Equal(t, int64(500), pay.gotAmount)          // передали правильную сумму
        require.Equal(t, []string{"paid"}, repo.updateCalls) // статус обновили ровно один раз
    })

    t.Run("платёж упал - статус не трогаем", func(t *testing.T) {
        t.Parallel()
        repo := &stubRepo{getFn: func(context.Context, int) (order.Order, error) { return okOrder, nil }}
        pay := &stubPayments{err: errors.New("gateway 503")}

        _, err := order.NewService(repo, pay).Pay(context.Background(), 1)

        require.Error(t, err)
        require.Empty(t, repo.updateCalls, "нельзя помечать оплаченным, если списание не прошло")
    })

    t.Run("деньги списаны, БД упала - ошибка несёт txID", func(t *testing.T) {
        t.Parallel()
        repo := &stubRepo{
            getFn:    func(context.Context, int) (order.Order, error) { return okOrder, nil },
            updateFn: func(context.Context, int, string) error { return errors.New("connection reset") },
        }
        pay := &stubPayments{txID: "tx-99"}

        txID, err := order.NewService(repo, pay).Pay(context.Background(), 1)

        require.Error(t, err)
        require.Equal(t, "tx-99", txID, "txID обязан вернуться наружу, иначе деньги потеряются")
        require.Contains(t, err.Error(), "tx-99")
    })

    t.Run("заказа нет", func(t *testing.T) {
        t.Parallel()
        repo := &stubRepo{getFn: func(context.Context, int) (order.Order, error) {
            return order.Order{}, order.ErrNotFound
        }}
        _, err := order.NewService(repo, &stubPayments{}).Pay(context.Background(), 1)

        require.ErrorIs(t, err, order.ErrNotFound)   // обёртка через %w сохранила цепочку
    })
}

Терминология: dummy, stub, spy, mock, fake

Те же пять дублёров, но теперь на одной шкале и с ответом на вопрос «чем платишь за каждый». Шкала выстроена не по «мощности», а по связанности теста с внутренним устройством кода: чем правее, тем больше тест знает о том, как именно код делает свою работу, - и тем чаще он ломается от рефакторинга, который ничего не сломал.

gomock: go.uber.org/mock

Оригинальный github.com/golang/mock заархивирован в 2023 году; поддерживается теперь форк go.uber.org/mock, туда и переехали генератор и рантайм. Поэтому ответ «пользуюсь golang/mock» звучит как «я давно не смотрел на экосистему».

$ go install go.uber.org/mock/mockgen@latest
$ mockgen -source=internal/order/service.go -destination=internal/order/mocks/mock_deps.go -package=mocks

У генератора четыре режима, в ходу два. Source mode (-source) читает конкретный файл и делает моки на все интерфейсы в нём - просто и предсказуемо. Package mode, в старых версиях reflect mode (mockgen database/sql/driver Conn,Driver), грузит пакет и достаёт интерфейс; он нужен для чужих пакетов. Раньше он делал это через рефлексию, в go.uber.org/mock с v0.5.0 - разбором исходников. Третий, archive mode, появился в v0.6.0: он берёт интерфейсы из собранного архива пакета и нужен в основном под Bazel. Четвёртый, gob mode (-model_gob, с v0.5.0), читает готовое описание пакета из файла и нужен тем, кто загружает пакеты своими средствами. Директиву обычно кладут прямо рядом с интерфейсом:

//go:generate mockgen -source=service.go -destination=mocks/mock_deps.go -package=mocks

func TestService_Pay_gomock(t *testing.T) {
    ctrl := gomock.NewController(t)   // ещё с golang/mock 1.5 Finish сам регистрируется в Cleanup
    repo := mocks.NewMockRepo(ctrl)
    pay  := mocks.NewMockPayments(ctrl)

    ctx := context.Background()
    o := order.Order{ID: 1, UserID: 7, Amount: 500, Status: "new"}

    // Матчеры: gomock.Any() (любой), gomock.Eq(x) (ровно x), gomock.Cond(func) (предикат).
    repo.EXPECT().
        Get(gomock.Any(), 1).
        Return(o, nil).
        Times(1)

    pay.EXPECT().
        Charge(gomock.Any(), 7, int64(500)).
        Return("tx-42", nil)          // без Times(...) ждём ровно один вызов

    repo.EXPECT().
        UpdateStatus(gomock.Any(), 1, "paid").
        Return(nil)

    got, err := order.NewService(repo, pay).Pay(ctx, 1)

    require.NoError(t, err)
    require.Equal(t, "tx-42", got)
    // Ожидания проверятся сами в t.Cleanup: любой невыполненный EXPECT
    // валит тест с внятным сообщением «missing call».
}

testify/mock

Альтернатива без кодогенерации: мок пишется руками поверх встраиваемой структуры mock.Mock. Так гибче в мелочах, но больше ручной работы, и мок легко расходится с интерфейсом: имена методов в ожиданиях - просто строки, и опечатку в них компилятор не поймает. Сигнатуры самого мока сверит строчка var _ order.Repo = (*MockRepo)(nil): ошибка всплывёт рядом с моком, а не там, где его передают в конструктор.

type MockRepo struct {
    mock.Mock
}

var _ order.Repo = (*MockRepo)(nil)   // страховка: расхождение с интерфейсом всплывёт прямо здесь

func (m *MockRepo) Get(ctx context.Context, id int) (order.Order, error) {
    args := m.Called(ctx, id)                  // регистрируем вызов и достаём заготовленный ответ
    return args.Get(0).(order.Order), args.Error(1)
}
func (m *MockRepo) UpdateStatus(ctx context.Context, id int, status string) error {
    return m.Called(ctx, id, status).Error(0)
}

func TestService_Pay_testify(t *testing.T) {
    repo := new(MockRepo)
    pay  := new(MockPayments)

    o := order.Order{ID: 1, UserID: 7, Amount: 500, Status: "new"}

    repo.On("Get", mock.Anything, 1).Return(o, nil).Once()
    pay.On("Charge", mock.Anything, 7, int64(500)).Return("tx-42", nil).Once()
    repo.On("UpdateStatus", mock.Anything, 1, "paid").Return(nil).Once()

    // Динамический ответ и произвольный матчер. Функцию из Return testify сам не вызывает:
    // её распознаёт метод мока (так сделаны моки mockery), а ручной args.String(0) на ней упадёт.
    // pay.On("Charge", mock.Anything, mock.MatchedBy(func(u int) bool { return u > 0 }), mock.Anything).
    //     Return(func(ctx context.Context, u int, a int64) string { return fmt.Sprintf("tx-%d", u) }, nil)

    _, err := order.NewService(repo, pay).Pay(context.Background(), 1)
    require.NoError(t, err)

    repo.AssertExpectations(t)          // без этой строки ожидания вообще не проверяются
    pay.AssertExpectations(t)
    repo.AssertNumberOfCalls(t, "UpdateStatus", 1)
    repo.AssertNotCalled(t, "UpdateStatus", mock.Anything, 1, "cancelled")
}

Когда моки вредят и почему фейк на map часто лучше

Мок фиксирует протокол: кто кого позвал, с чем и сколько раз. Значит, тест начинает знать внутреннее устройство метода. Допустим, ты переписал Pay, и вместо двух вызовов Get + UpdateStatus теперь делается один UpdateStatusIfNew. Поведение снаружи не изменилось ни на байт, а двадцать тестов красные. Тест, который падает при рефакторинге без изменения поведения, ничего не ловит, он просто берёт налог с каждой правки.

repo.EXPECT().Get(gomock.Any(), 1).
    Return(o, nil).Times(1)
repo.EXPECT().UpdateStatus(gomock.Any(), 1, "paid").
    Return(nil).Times(1)

_, err := svc.Pay(ctx, 1)
require.NoError(t, err)
// Проверили: "сервис сделал ровно эти два вызова" (порядок - только с InOrder или After).
// Не проверили: а заказ-то стал оплаченным?
// Поменяли реализацию на один запрос, и тест покраснел.

repo := newFakeRepo(o)          // map внутри
_, err := svc.Pay(ctx, 1)
require.NoError(t, err)

got, _ := repo.Get(ctx, 1)
require.Equal(t, "paid", got.Status)
// Проверили наблюдаемый эффект: заказ оплачен.
// Как именно сервис этого добился, уже его дело.
// Рефакторинг тест не ломает.

// Весь фейк-репозиторий: три десятка строк, пишется один раз на пакет.
type fakeRepo struct {
    mu     sync.Mutex
    orders map[int]order.Order
    failOn map[int]error        // чтобы смоделировать сбой конкретной строки
}

func newFakeRepo(seed ...order.Order) *fakeRepo {
    r := &fakeRepo{orders: map[int]order.Order{}, failOn: map[int]error{}}
    for _, o := range seed {
        r.orders[o.ID] = o
    }
    return r
}

func (r *fakeRepo) Get(_ context.Context, id int) (order.Order, error) {
    r.mu.Lock(); defer r.mu.Unlock()
    if err := r.failOn[id]; err != nil {
        return order.Order{}, err
    }
    o, ok := r.orders[id]
    if !ok {
        return order.Order{}, order.ErrNotFound      // ведёт себя как настоящий: тот же сентинель
    }
    return o, nil
}

func (r *fakeRepo) UpdateStatus(_ context.Context, id int, status string) error {
    r.mu.Lock(); defer r.mu.Unlock()
    o, ok := r.orders[id]
    if !ok {
        return order.ErrNotFound
    }
    o.Status = status
    r.orders[id] = o
    return nil
}

httptest: обе стороны HTTP

Пакет net/http/httptest закрывает два разных сценария, и их регулярно путают. ResponseRecorder нужен, когда тестируем свой хендлер: сети нет вообще, хендлер вызывается как обычная функция. httptest.NewServer берут, когда тестируем свой клиент: поднимается настоящий сервер на 127.0.0.1 со свободным портом.

Сторона сервера: ResponseRecorder

func TestPayHandler(t *testing.T) {
    tests := []struct {
        name       string
        body       string
        svcTxID    string
        svcErr     error
        wantCode   int
        wantBody   string
    }{
        {name: "успех", body: `{"order_id":1}`, svcTxID: "tx-42",
            wantCode: http.StatusOK, wantBody: `{"tx_id":"tx-42"}`},
        {name: "битый json", body: `{`,
            wantCode: http.StatusBadRequest},
        {name: "нет заказа", body: `{"order_id":9}`, svcErr: order.ErrNotFound,
            wantCode: http.StatusNotFound},
        {name: "шлюз лёг", body: `{"order_id":1}`, svcErr: paygate.ErrUnavailable,
            wantCode: http.StatusBadGateway},
    }

    for _, tc := range tests {
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            h := NewPayHandler(stubPayer{txID: tc.svcTxID, err: tc.svcErr})

            req := httptest.NewRequest(http.MethodPost, "/orders/pay", strings.NewReader(tc.body))
            req.Header.Set("Content-Type", "application/json")
            rec := httptest.NewRecorder()          // реализует http.ResponseWriter, копит ответ в памяти

            h.ServeHTTP(rec, req)                  // прямой вызов: ни сокета, ни порта, ни таймаутов

            res := rec.Result()
            defer res.Body.Close()
            require.Equal(t, tc.wantCode, res.StatusCode)
            if tc.wantBody != "" {
                body, _ := io.ReadAll(res.Body)
                require.JSONEq(t, tc.wantBody, string(body))
            }
        })
    }
}

Сторона клиента: httptest.NewServer

func TestPaygateClient_Charge(t *testing.T) {
    var gotBody []byte
    var gotAuth string
    var calls int32

    srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        atomic.AddInt32(&calls, 1)
        gotAuth = r.Header.Get("Authorization")
        gotBody, _ = io.ReadAll(r.Body)

        assert.Equal(t, "/v1/charges", r.URL.Path)    // горутина сервера: только assert, не require
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte(`{"id":"tx-42","status":"succeeded"}`))
    }))
    defer srv.Close()          // Close ждёт завершения всех активных запросов

    // Клиенту подсовываем базовый URL тестового сервера, ради этого он и параметризован.
    c := paygate.New(srv.URL, "secret-token", srv.Client())

    tx, err := c.Charge(context.Background(), 7, 500)

    require.NoError(t, err)
    require.Equal(t, "tx-42", tx)
    require.Equal(t, "Bearer secret-token", gotAuth)
    require.JSONEq(t, `{"user_id":7,"amount":500}`, string(gotBody))
    require.EqualValues(t, 1, atomic.LoadInt32(&calls))
}

Ещё три приёма, которые стоит назвать:

• httptest.NewTLSServer поднимает сервер по HTTPS с самоподписанным сертификатом. Ходить в него надо клиентом srv.Client(): у него уже подложен нужный корневой сертификат. Отключать проверку через InsecureSkipVerify в тестах не нужно.
• Подмена транспорта выручает, если клиент не даёт передать базовый URL: можно подсунуть свой http.RoundTripper. Это точка расширения ниже уровня URL, через неё удобно моделировать таймауты, обрывы и ретраи без реального сервера.
• Моделирование сбоев тестовому серверу даётся легко: он отдаёт 500, 429 с Retry-After, обрезанное тело, зависание дольше клиентского таймаута (time.Sleep в хендлере - редкое место, где sleep оправдан: ты моделируешь медленную сеть, а не ждёшь горутину).

// Подмена транспорта: клиент даже не подозревает, что сети нет.
type roundTripFunc func(*http.Request) (*http.Response, error)

func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }

func TestClient_RetriesOn503(t *testing.T) {
    var n int
    rt := roundTripFunc(func(r *http.Request) (*http.Response, error) {
        n++
        if n < 3 {
            return &http.Response{StatusCode: 503, Body: io.NopCloser(strings.NewReader(""))}, nil
        }
        return &http.Response{
            StatusCode: 200,
            Body:       io.NopCloser(strings.NewReader(`{"id":"tx-1"}`)),
            Header:     http.Header{"Content-Type": []string{"application/json"}},
        }, nil
    })

    c := paygate.New("https://api.example.com", "tok", &http.Client{Transport: rt})
    tx, err := c.Charge(context.Background(), 7, 500)

    require.NoError(t, err)
    require.Equal(t, "tx-1", tx)
    require.Equal(t, 3, n, "ожидали две неудачные попытки и одну успешную")
}

Пирамида тестирования и антипаттерн «рожок мороженого»

Модель Майка Кона: чем ниже уровень, тем тестов больше, тем они быстрее, дешевле и точнее локализуют поломку. Чем выше - тем меньше, медленнее и дороже, зато они проверяют то, чего не видит ни один юнит-тест: что все части собраны вместе и реально работают.

Интеграционные тесты: testcontainers-go

Идея простая: раз тесту нужен настоящий PostgreSQL, пусть тест сам его и поднимет. Библиотека github.com/testcontainers/testcontainers-go запускает контейнер через Docker API, дожидается готовности и отдаёт хост со случайным свободным портом. Это лучше «поднятой заранее базы на 5432»: тесты не дерутся за порт, прогон воспроизводится на ноутбуке и в CI одинаково, а версия PostgreSQL зафиксирована тегом образа.

//go:build integration

package postgres_test

import (
    "context"
    "database/sql"
    "fmt"
    "os"
    "testing"
    "time"

    _ "github.com/jackc/pgx/v5/stdlib"
    "github.com/stretchr/testify/require"
    "github.com/testcontainers/testcontainers-go"
    tcpostgres "github.com/testcontainers/testcontainers-go/modules/postgres"
    "github.com/testcontainers/testcontainers-go/wait"

    "example.com/shop/internal/order"
    "example.com/shop/internal/postgres"   // пакет под тестом: имя совпадает с модулем, отсюда tcpostgres
)

var testDB *sql.DB

// TestMain: контейнер поднимается один раз на весь пакет.
func TestMain(m *testing.M) {
    ctx := context.Background()

    pg, err := tcpostgres.Run(ctx, "postgres:16-alpine",
        tcpostgres.WithDatabase("app_test"),
        tcpostgres.WithUsername("test"),
        tcpostgres.WithPassword("test"),
        // Ждём готовности базы, а не порта: entrypoint образа сначала поднимает
        // PostgreSQL только на unix-сокете для инициализации, останавливает
        // и запускает снова, отсюда Occurrence(2).
        testcontainers.WithWaitStrategy(
            wait.ForLog("database system is ready to accept connections").
                WithOccurrence(2).
                WithStartupTimeout(60*time.Second),
        ),
    )
    if err != nil {
        fmt.Fprintf(os.Stderr, "поднять postgres: %v\n", err)
        os.Exit(1)
    }

    dsn, err := pg.ConnectionString(ctx, "sslmode=disable")
    if err != nil {
        fmt.Fprintf(os.Stderr, "dsn: %v\n", err)
        os.Exit(1)
    }
    testDB, err = sql.Open("pgx", dsn)
    if err != nil {
        fmt.Fprintf(os.Stderr, "подключиться: %v\n", err)
        os.Exit(1)
    }
    if err := applyMigrations(testDB); err != nil {   // миграции один раз на контейнер
        fmt.Fprintf(os.Stderr, "миграции: %v\n", err)
        os.Exit(1)
    }

    code := m.Run()

    // os.Exit не выполняет defer: убираем руками и до выхода.
    _ = testDB.Close()
    _ = testcontainers.TerminateContainer(pg)
    os.Exit(code)
}

// Изоляция: каждый тест работает в своей транзакции, которая всегда откатывается.
func withTx(t *testing.T) *sql.Tx {
    t.Helper()
    tx, err := testDB.BeginTx(context.Background(), nil)
    if err != nil {
        t.Fatalf("begin: %v", err)
    }
    t.Cleanup(func() { _ = tx.Rollback() })   // именно Cleanup, а не defer в хелпере
    return tx
}

func TestOrderRepo_GetUpdate(t *testing.T) {
    ctx := context.Background()

    t.Run("несуществующий заказ", func(t *testing.T) {
        repo := postgres.NewOrderRepo(withTx(t))   // репозиторий умеет работать с любым Querier
        _, err := repo.Get(ctx, 999999)
        require.ErrorIs(t, err, order.ErrNotFound)   // проверяем именно маппинг sql.ErrNoRows
    })

    t.Run("уникальный индекс", func(t *testing.T) {
        // Транзакция своя на каждый подтест: после ошибки 23505 PostgreSQL
        // отвергает в ней любой запрос (25P02) до самого отката.
        repo := postgres.NewOrderRepo(withTx(t))
        require.NoError(t, repo.Create(ctx, order.Order{ID: 1, UserID: 7, Amount: 500}))
        err := repo.Create(ctx, order.Order{ID: 1, UserID: 7, Amount: 500})
        require.ErrorIs(t, err, order.ErrDuplicate) // 23505 превратился в доменную ошибку
    })

    t.Run("маппинг NULL и timestamptz", func(t *testing.T) {
        // То, чего фейк на map не проверит никогда:
        // NULL в nullable-поле, часовой пояс, точность numeric, длина varchar.
    })
}

Билд-теги: разделение прогонов

Строка //go:build integration исключает файл из обычной сборки. Пустую строку после неё и до package gofmt ставит сам, а обязательной она была только у старого синтаксиса «// +build». Дальше:

$ go test ./...                          # быстрые: секунды, докер не нужен
$ go test -tags=integration ./...        # медленные: нужен docker
$ go test -tags=integration -run TestOrderRepo -count=1 ./internal/postgres

# .github/workflows/ci.yml: два независимых job'а
jobs:
  unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with: { go-version: '1.27' }
      - run: go test -race -covermode=atomic -coverprofile=cover.out ./...

  integration:
    runs-on: ubuntu-latest          # docker доступен из коробки, testcontainers сам всё поднимет
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with: { go-version: '1.27' }
      - run: go test -tags=integration -race -timeout=15m ./...

Вместо билд-тегов можно поставить переключатель в рантайме. Он проще (не надо помнить про тег и про то, что IDE по умолчанию файл не подсвечивает), но файл всё равно компилируется:

func requireDocker(t *testing.T) {
    t.Helper()
    if testing.Short() {
        t.Skip("пропуск интеграционного теста: -short")   // go test -short ./...
    }
    // Проверка по переменным вроде DOCKER_HOST врёт: Docker Desktop её не ставит.
    testcontainers.SkipIfProviderIsNotHealthy(t)   // пропуск, если docker недоступен
}

Третий вариант, docker-compose, выручает, когда сервисов много и они должны видеть друг друга (база + Kafka + Redis + сам сервис). В GitHub Actions есть ещё services: - контейнеры поднимает сам раннер, а тест получает готовый адрес через переменные окружения.

# docker-compose.test.yml: вариант для локального прогона и «тяжёлого» CI
services:
  postgres:
    image: postgres:16-alpine
    environment: { POSTGRES_PASSWORD: test, POSTGRES_DB: app_test }
    healthcheck:                       # без healthcheck тесты стартуют раньше базы
      # -h localhost: через unix-сокет проверка пройдёт ещё на время инициализации
      test: ["CMD-SHELL", "pg_isready -h localhost -U postgres -d app_test"]
      interval: 2s
      timeout: 3s
      retries: 15
  tests:
    build: { context: ., dockerfile: Dockerfile.test }
    depends_on:
      postgres: { condition: service_healthy }
    environment:
      DATABASE_DSN: postgres://postgres:test@postgres:5432/app_test?sslmode=disable
    command: ["go", "test", "-tags=integration", "-race", "./..."]

Тестирование кода с горутинами и каналами

Всё остальное здесь вытекает из одного правила: тест не имеет права зависеть от скорости планировщика. Планировщик Go не даёт никаких гарантий на порядок и момент запуска горутины; на ноутбуке с 10 ядрами и на CI-раннере с двумя, да ещё под -race (замедление в 2–20 раз), тайминги отличаются на порядок. Значит, любая «пауза» в тесте рано или поздно станет флаком.

func TestWorker_Bad(t *testing.T) {
    w := NewWorker()
    go w.Run()

    w.Submit(Job{ID: 1})
    time.Sleep(100 * time.Millisecond)  // «ну, должно хватить»

    if got := w.Processed(); got != 1 {
        t.Fatalf("got %d", got)
    }
}
// Три беды сразу:
// 1) на нагруженном раннере 100 мс не хватит, и билд упадёт на ровном месте;
// 2) даже в зелёном прогоне каждый такой тест выбрасывает 100 мс в мусор;
// 3) горутина w.Run() живёт и после теста, это утечка.

func TestWorker_Good(t *testing.T) {
    ctx, cancel := context.WithCancel(context.Background())
    t.Cleanup(cancel)

    w := NewWorker()
    done := make(chan struct{})
    go func() { defer close(done); w.Run(ctx) }()

    processed := make(chan int, 1)
    w.OnDone = func(id int) { processed <- id }   // сигнал вместо угадывания времени

    w.Submit(Job{ID: 1})

    select {
    case id := <-processed:
        require.Equal(t, 1, id)
    case <-time.After(2 * time.Second):
        t.Fatal("задача не обработана за 2 с")     // таймаут здесь только страховка
    }

    cancel()
    select {
    case <-done:                                   // дождались завершения горутины
    case <-time.After(time.Second):
        t.Fatal("Run не завершился по отмене контекста")
    }
}

goleak: поиск утечек горутин

Горутина утекает, когда остаётся заблокированной навсегда: чтение из канала, в который больше никто не пишет, отправка в канал без читателя, забытый ticker.Stop(), worker без отмены. Рантайм её не соберёт: горутина служит корнем для GC, так что вместе с ней утекает весь её стек и всё, на что она ссылается. В проде это выглядит как ползущий вверх график памяти и runtime.NumGoroutine().

go.uber.org/goleak делает простую вещь: снимает дамп стеков через runtime.Stack и сравнивает список горутин с ожидаемым, отфильтровывая системные (GC, финализаторы, testing сам). Подключается одной строкой:

// Вариант 1: на весь пакет.
func TestMain(m *testing.M) {
    goleak.VerifyTestMain(m,
        // Пропускаем «вечные» горутины сторонних библиотек, иначе будет ложное срабатывание.
        goleak.IgnoreTopFunction("github.com/jackc/pgx/v5/pgxpool.(*Pool).backgroundHealthCheck"),
        goleak.IgnoreAnyFunction("go.opencensus.io/stats/view.(*worker).start"),
    )
}

// Вариант 2: точечно, на один тест. Так удобнее: видно, какой тест течёт.
func TestPipeline(t *testing.T) {
    defer goleak.VerifyNone(t)     // именно defer: проверка после завершения теста
    ...
}

$ go test ./pipeline
--- FAIL: TestPipeline (0.45s)
    pipeline_test.go:12: found unexpected goroutines:
        [Goroutine 20 in state chan receive, with app/pipeline.worker on top of the stack:
        app/pipeline.worker(0x1ce287422230)
        	/app/pipeline/worker.go:7 +0x68
        created by app/pipeline.Start in goroutine 19
        	/app/pipeline/pipeline.go:11 +0xcc
        ]
FAIL
FAIL	app/pipeline	0.454s
FAIL

type Repo interface {
    Get(ctx context.Context, id int) (Order, error)
    UpdateStatus(ctx context.Context, id int, status string) error
}
type Payments interface {
    Charge(ctx context.Context, userID int, amount int64) (string, error)
}

func NewService(r Repo, p Payments) *Service { return &Service{repo: r, pay: p} }

func TestPay_gomock(t *testing.T) {
    ctrl := gomock.NewController(t)             // Finish регистрируется в t.Cleanup сам
    repo := mocks.NewMockRepo(ctrl)
    pay  := mocks.NewMockPayments(ctrl)

    o := order.Order{ID: 1, UserID: 7, Amount: 500, Status: "new"}

    repo.EXPECT().Get(gomock.Any(), 1).Return(o, nil)
    pay.EXPECT().Charge(gomock.Any(), 7, int64(500)).Return("tx-42", nil)
    repo.EXPECT().UpdateStatus(gomock.Any(), 1, "paid").Return(nil)

    got, err := order.NewService(repo, pay).Pay(context.Background(), 1)
    require.NoError(t, err)
    require.Equal(t, "tx-42", got)
}

h := NewPayHandler(stubPayer{txID: "tx-42"})

req := httptest.NewRequest(http.MethodPost, "/orders/pay", strings.NewReader(`{"order_id":1}`))
req.Header.Set("Content-Type", "application/json")
rec := httptest.NewRecorder()

h.ServeHTTP(rec, req)          // прямой вызов: ни сокета, ни таймаутов, ни портов

res := rec.Result()
defer res.Body.Close()
require.Equal(t, http.StatusOK, res.StatusCode)
body, _ := io.ReadAll(res.Body)
require.JSONEq(t, `{"tx_id":"tx-42"}`, string(body))

srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    gotAuth = r.Header.Get("Authorization")
    gotBody, _ = io.ReadAll(r.Body)
    w.WriteHeader(200)
    _, _ = w.Write([]byte(`{"id":"tx-42"}`))
}))
defer srv.Close()                     // Close дожидается активных запросов

c := paygate.New(srv.URL, "secret", srv.Client())
tx, err := c.Charge(ctx, 7, 500)

require.NoError(t, err)
require.Equal(t, "tx-42", tx)
require.Equal(t, "Bearer secret", gotAuth)      // проверяем в тесте, а не в хендлере

func TestMain(m *testing.M) {
    ctx := context.Background()
    pg, err := postgres.Run(ctx, "postgres:16-alpine",
        postgres.WithDatabase("app_test"),
        postgres.WithUsername("test"), postgres.WithPassword("test"),
        testcontainers.WithWaitStrategy(
            wait.ForLog("database system is ready to accept connections").
                WithOccurrence(2).WithStartupTimeout(60*time.Second)),
    )
    if err != nil { os.Exit(1) }

    dsn, _ := pg.ConnectionString(ctx, "sslmode=disable")
    testDB, _ = sql.Open("pgx", dsn)
    _ = applyMigrations(testDB)          // один раз на контейнер

    code := m.Run()

    _ = testDB.Close()                   // os.Exit не выполняет defer, убираем руками
    _ = testcontainers.TerminateContainer(pg)
    os.Exit(code)
}

tx, _ := db.BeginTx(ctx, nil)
t.Cleanup(func(){ _ = tx.Rollback() })
repo := postgres.NewOrderRepo(tx)

TRUNCATE orders, payments
  RESTART IDENTITY CASCADE;

//go:build integration
                                  // пустая строка перед package нужна старому // +build
package postgres_test

$ go test ./...                       # быстрый прогон, докер не нужен
$ go test -tags=integration -race -timeout=15m ./...

// Правильный каркас: сигнал + таймаут + проверка завершения
ctx, cancel := context.WithCancel(context.Background())
t.Cleanup(cancel)

done := make(chan struct{})
go func() { defer close(done); w.Run(ctx) }()

processed := make(chan int, 1)
w.OnDone = func(id int) { processed <- id }
w.Submit(Job{ID: 1})

select {
case id := <-processed:
    require.Equal(t, 1, id)
case <-time.After(2 * time.Second):
    t.Fatal("задача не обработана за 2 с")    // таймаут не для ожидания, а для внятного сообщения
}

cancel()
select {
case <-done:                                   // проверяем, что горутина вышла по отмене
case <-time.After(time.Second):
    t.Fatal("Run не завершился по отмене контекста")
}

func TestMain(m *testing.M) { goleak.VerifyTestMain(m) }   // на весь пакет
func TestPipeline(t *testing.T) { defer goleak.VerifyNone(t); ... }   // точечно

Что стоит запомнить

• Stub задаёт ответы, spy записывает обращения, fake реализует упрощённое поведение, mock проверяет ожидания.
• Consumer-side interface выражает только нужное поведение.
• Fake подходит, если тесту нужны данные и семантика, а не точные вызовы.

Частые ошибки

• Mock не проверяет SQL/транзакцию.
• Не делай интерфейс копией всей реализации.

type fakeStore struct { items map[string]Item }
func (f fakeStore) Get(_ context.Context, id string) (Item, error) { return f.items[id], nil }
func Load(s Store, id string) (Item, error) { return s.Get(context.Background(), id) }

func TestLoad(t *testing.T) {
  mockStore.EXPECT().Get(gomock.Any(), id).Return(item, nil).Times(2)
  got, err := service.Load(ctx, id)
  if err != nil { t.Fatal(err) }
  if got != item { t.Fatalf("got %#v want %#v", got, item) }
}