Тестирование

5.1Юнит-тесты

Пакет testing фреймворком не назовёшь: это тонкая обвязка над обычным Go-кодом. Большинство «странностей» тестов (почему t.Fatal нельзя из горутины, почему параллельный сабтест видит закрытую базу) объясняется одной строчкой из рантайма. По ней и видно, кто механику понял, а кто ответ заучил.

Сначала — шесть слов, которые дальше идут как общеизвестные

Тесту можно верить, когда он падает при сломанном коде и молчит, когда всё в порядке. Инструменты для такого теста зовутся шестью словами, и половина из них так и осталась без перевода с английского.

1. Табличный тест — список случаев плюс один общий цикл проверки

Есть двадцать пар «вход → ожидаемый выход». Можно написать двадцать почти одинаковых функций, а можно один слайс структур (это и есть «таблица») и один цикл, который прогоняет каждую строку через одну и ту же проверку. Второе и называется табличным тестом (table-driven test), и в Go так пишут по умолчанию.

Строк выходит меньше, но ценно другое: тест отделяет данные от логики проверки. Новый случай добавляется одной строкой в таблице, копировать функцию не нужно. И читается такой тест как список требований к коду.

2. Фикстура — заранее заготовленные входные данные для теста

Фикстурой (fixture, «нечто закреплённое») называют подготовленное состояние, с которого тест начинает: заполненный объект Order, JSON-пейлоад настоящего запроса, дамп базы, набор строк в таблице. Живёт либо файлом в директории testdata/, либо функцией-конструктором в коде теста.

Слово путает тем, что в других языках (pytest, JUnit) «фикстурой» называют ещё и setup/teardown — код подготовки и уборки. В Go эту роль играют TestMain и t.Cleanup, а фикстурой обычно зовут именно данные.

3. Golden file — файл-эталон, с которым сравнивают вывод

Иногда ожидаемый результат слишком велик, чтобы писать его литералом прямо в тесте: отрендеренный HTML на 200 строк, сгенерированный SQL, большой JSON-ответ. Тогда эталон кладут отдельным файлом рядом с тестом, а тест сравнивает свой вывод с содержимым этого файла. Такой файл называют golden file («золотой», то есть образцовый) или просто «эталоном».

У приёма есть фирменная особенность: специальный флаг (обычно -update) перезаписывает эталон текущим выводом. В этом его удобство и главная опасность, к которой ещё вернёмся.

4. Покрытие — доля кода, которую тесты хотя бы один раз исполнили

Покрытие (coverage) отвечает на вопрос «сколько кода вообще побывало под тестом». Считается механически: при сборке в каждый кусок кода вставляется счётчик, прогон тестов их взводит, а go test -cover печатает долю взведённых. «Покрытие 72 %» означает буквально «72 % операторов пакета хоть раз выполнились, пока шли тесты».

На этом часто ловят: покрытие показывает, что строка исполнилась, а не что её результат проверили. Тест без единого сравнения даст те же проценты, что и тест с двадцатью. Цифра хорошо находит места, куда «вообще никто не заходил», а качество тестов по ней не оценить (об этом отдельный раздел ниже).

5. Фаззинг — тест, который сам придумывает входные данные

Фаззинг (fuzzing, от fuzz — «пух», «размытость») переворачивает обычную схему. В обычном тесте ты сам пишешь вход и проверяешь конкретный ответ. В фаззинге входы, миллионы вариантов, генерирует движок, а проверяешь ты уже свойство, которое обязано выполняться всегда: «не паникует», «не зацикливается», «разобрал и собрал обратно — получилось то же самое».

Фаззер в Go coverage-guided, то есть «направляемый покрытием». Случайные байты вслепую он не бросает: следит, какие ветки кода открыл очередной вход, и дальше мутирует те входы, что залезли в новый код. Так он находит то, до чего руками не додумаешься.

6. Корпус — накопленный набор входов для фаззера

Корпусом (corpus, «свод») называют набор входных данных, на которых работает фаззер. Частей у него две. Семенной корпус (seed corpus) ты собираешь руками: несколько реальных примеров и несколько заведомо злых. Сгенерированный корпус движок наполняет сам и сохраняет в него каждый вход, который открыл новую ветку кода.

Когда фаззер находит падение, он записывает виновный вход файлом в testdata/fuzz/. С этого момента вход становится обычным тест-кейсом и прогоняется на каждом go test, так что у бага сразу появляется регрессионный тест.

Что происходит, когда ты набираешь go test

go test и компилирует, и генерирует код. Он собирает три группы файлов в один временный бинарь и запускает его:

• Сам пакет — order.go, package order.
• Внутренние тесты лежат в order_test.go с package order. Видят неэкспортируемые идентификаторы, могут тестировать приватную функцию напрямую.
• Внешние тесты объявлены в отдельном файле, например order_ext_test.go, как package order_test. Единственный случай, когда в одной директории вместе собираются два имени пакета. Видят только публичный API, зато могут импортировать пакеты, которые импортируют order, и циклов не возникает. Так тестируется net/http изнутри стандартной библиотеки.

Дальше go test генерирует файл _testmain.go: в нём func main(), списки найденных TestXxx, BenchmarkXxx, FuzzXxx, ExampleXxx и вызов testing.MainStart, а за ним m.Run() или твой TestMain. Никакой рефлексии в рантайме, никакого сканирования — список тестов фиксируется на этапе сборки, поэтому «динамически зарегистрировать тест» в Go можно только сабтестом через t.Run.

Имя теста ищется по префиксу: после Test должна идти не строчная буква. func Testfoo не запустится. Раньше это случалось молча — классическая потеря часа жизни; с Go 1.24 go test сам гоняет vet-анализатор tests, и он такое имя ловит. Тест запускается из директории своего пакета, поэтому относительные пути вида testdata/x.json всегда работают.

Анатомия: t.Run, t.Helper, t.Cleanup и компания

func TestOrderService(t *testing.T) {
    // 1. Изолируем окружение: после теста значение восстановится само.
    t.Setenv("APP_ENV", "test")          // паникует, если тест параллельный
    dir := t.TempDir()                   // своя директория, удалится сама
    ctx := t.Context()                   // Go 1.24: отменяется перед Cleanup

    db := openDB(t, dir)
    t.Cleanup(func() { db.Close() })     // не defer: разница видна на параллельных сабтестах

    // 2. Сабтест: своё имя, свой *testing.T, своя горутина.
    t.Run("создание заказа", func(t *testing.T) {
        got, err := New(db).Create(ctx, "user-1")
        requireNoErr(t, err)             // хелпер, см. ниже
        if got.Status != "new" {
            t.Errorf("status = %q, хотим %q", got.Status, "new")
        }
    })

    t.Run("пустой пользователь", func(t *testing.T) {
        _, err := New(db).Create(ctx, "")
        if !errors.Is(err, ErrNoUser) {
            t.Fatalf("err = %v, хотим ErrNoUser", err)
        }
    })
}

// С t.Helper() строка ошибки укажет на вызывающего, а не на эту функцию.
func requireNoErr(t *testing.T, err error) {
    t.Helper()
    if err != nil {
        t.Fatalf("неожиданная ошибка: %v", err)
    }
}

// $ go test -v
// === RUN   TestOrderService
// === RUN   TestOrderService/создание_заказа
// === RUN   TestOrderService/пустой_пользователь
// --- PASS: TestOrderService (0.00s)
//     --- PASS: TestOrderService/создание_заказа (0.00s)
//     --- PASS: TestOrderService/пустой_пользователь (0.00s)
// PASS
// ok  	order	0.273s
//
// Сабтест печатается отдельной строкой «=== RUN» с именем через слэш;
// пробелы в имени заменяются на подчёркивания. Время у каждого своё,
// а последнее число меняется от запуска к запуску.

func TestRenderPDF(t *testing.T) {
    got, err := Render(fixtureInvoice(t))
    if err != nil { t.Fatal(err) }

    if !bytes.Equal(got, want) {
        // Кладём фактический результат рядом: в CI его можно скачать и открыть.
        path := filepath.Join(t.ArtifactDir(), "actual.pdf")
        if err := os.WriteFile(path, got, 0o644); err != nil { t.Fatal(err) }
        t.Fatalf("рендер разошёлся с эталоном, факт сохранён в %s", path)
    }
}

$ go test ./...                                   # ArtifactDir = временная папка, удалится
$ mkdir -p ./out
$ go test -artifacts -outputdir=./out ./...       # файлы останутся в ./out/_artifacts/

TestMain: единственная точка глобального setup

var testDB *sql.DB

func TestMain(m *testing.M) {
    // flag.Parse() вызывать не нужно, m.Run() сделает это сам,
    // но свои флаги надо объявить до m.Run().
    ctx := context.Background()
    ctr, dsn := startPostgres(ctx)        // контейнер поднимается один раз на пакет
    testDB = mustOpen(dsn)
    mustMigrate(testDB)

    code := m.Run()                       // здесь бегут все тесты пакета

    testDB.Close()
    ctr.Terminate(ctx)                    // os.Exit не выполнит defer, убираем руками
    os.Exit(code)
}

Если TestMain объявлен, тестовый бинарь вызывает его вместо прямого запуска тестов. С Go 1.15 os.Exit(code) необязателен: если TestMain просто вернётся, обёртка сама передаст результат m.Run() в os.Exit. Но привычка писать os.Exit живёт, и вместе с ней живёт баг: os.Exit не выполняет defer. Контейнер остаётся висеть, файлы не удаляются.

Табличные тесты: как их пишут, чтобы они не сгнили

Табличный тест держится на разделении данных и проверки, и отсюда главное правило: тело цикла должно быть единственным путём исполнения. Если внутри появились if tc.kind == ..., таблица распалась на два разных теста и её пора разделить.

// --- код под тестом -------------------------------------------------
var (
    ErrLoginEmpty   = errors.New("login is empty")
    ErrLoginTooLong = errors.New("login is too long")
    ErrBadEmail     = errors.New("email is invalid")
    ErrWeakPassword = errors.New("password is too weak")
)

type Signup struct {
    Login, Email, Password string
}

func Validate(s Signup) error {
    switch {
    case s.Login == "":
        return ErrLoginEmpty
    case utf8.RuneCountInString(s.Login) > 32:
        return fmt.Errorf("%w: %d рун", ErrLoginTooLong, utf8.RuneCountInString(s.Login))
    case !strings.Contains(s.Email, "@"):
        return ErrBadEmail
    case len(s.Password) < 8:
        return ErrWeakPassword
    }
    return nil
}

// --- тест -----------------------------------------------------------
func TestValidate(t *testing.T) {
    valid := Signup{Login: "gopher", Email: "g@example.com", Password: "hunter22"}

    // Хелпер-мутатор копирует валидный объект и вносит одну правку,
    // так негативный кейс отличается от позитивного ровно одним полем.
    with := func(f func(*Signup)) Signup { s := valid; f(&s); return s }

    tests := []struct {
        name string
        in   Signup
        want error          // nil = ожидаем успех
    }{
        {"валидный", valid, nil},
        {"логин пустой", with(func(s *Signup) { s.Login = "" }), ErrLoginEmpty},
        {"логин ровно 32 руны", with(func(s *Signup) { s.Login = strings.Repeat("я", 32) }), nil},
        {"логин 33 руны", with(func(s *Signup) { s.Login = strings.Repeat("я", 33) }), ErrLoginTooLong},
        {"email без собаки", with(func(s *Signup) { s.Email = "gexample.com" }), ErrBadEmail},
        {"пароль 7 символов", with(func(s *Signup) { s.Password = "1234567" }), ErrWeakPassword},
        {"пароль ровно 8", with(func(s *Signup) { s.Password = "12345678" }), nil},
    }

    for _, tc := range tests {
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            err := Validate(tc.in)
            // errors.Is, а не err == tc.want и не сравнение строк:
            // ErrLoginTooLong обёрнут через %w и содержит количество рун.
            if !errors.Is(err, tc.want) {
                t.Fatalf("Validate() = %v, хотим %v", err, tc.want)
            }
        })
    }
}

Когда сравниваются структуры, а не ошибки, reflect.DeepEqual даёт бесполезное «not equal». Стандартом де-факто стал github.com/google/go-cmp: он печатает diff и умеет игнорировать поля.

if diff := cmp.Diff(want, got, cmpopts.IgnoreFields(Order{}, "CreatedAt", "ID")); diff != "" {
    t.Errorf("Order mismatch (-want +got):\n%s", diff)
}

t.Parallel: что происходит на самом деле

t.Parallel() ничего не отправляет в фон, он означает «поставь меня на паузу и разбуди вместе с остальными». Внутри метод делает две вещи: сигналит родителю, что тот может продолжать, и блокируется на канале-барьере родителя. Родительский t.Run возвращает управление немедленно, цикл идёт дальше, и так все сабтесты копятся на барьере. Барьер закрывается только тогда, когда тело родительской функции полностью вернулось.

// Плохо: база закроется в t1
func TestRepo(t *testing.T) {
    db := openDB(t)
    defer db.Close()

    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            // sql: database is closed
            _ = db.PingContext(t.Context())
        })
    }
}

// Хорошо: Cleanup дождётся детей (t3)
func TestRepo(t *testing.T) {
    db := openDB(t)
    t.Cleanup(func() { db.Close() })

    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            // соединение живо
            _ = db.PingContext(t.Context())
        })
    }
}

Что выведет код?

Модуль с go 1.21 в go.mod, запуск go test -v:

func TestSum(t *testing.T) {
    cases := []struct {
        name     string
        a, b, want int
    }{
        {"два плюс два", 2, 2, 4},
        {"два плюс три", 2, 3, 6}, // намеренно сломанный кейс
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            if got := tc.a + tc.b; got != tc.want {
                t.Errorf("%s: %d, хотим %d", tc.name, got, tc.want)
            }
        })
    }
}

$ go test -v
=== RUN   TestSum
=== RUN   TestSum/два_плюс_два
=== PAUSE TestSum/два_плюс_два
=== RUN   TestSum/два_плюс_три
=== PAUSE TestSum/два_плюс_три
=== CONT  TestSum/два_плюс_два
=== CONT  TestSum/два_плюс_три
=== NAME  TestSum/два_плюс_два
    sum_test.go:17: два плюс три: 5, хотим 6
=== NAME  TestSum/два_плюс_три
    sum_test.go:17: два плюс три: 5, хотим 6
--- FAIL: TestSum (0.00s)
    --- FAIL: TestSum/два_плюс_два (0.00s)
    --- FAIL: TestSum/два_плюс_три (0.00s)
FAIL
exit status 1
FAIL	sum	0.348s

$ go test
--- FAIL: TestSum (0.00s)
    --- FAIL: TestSum/два_плюс_два (0.00s)
        sum_test.go:17: два плюс три: 5, хотим 6
    --- FAIL: TestSum/два_плюс_три (0.00s)
        sum_test.go:17: два плюс три: 5, хотим 6
FAIL
exit status 1
FAIL	sum	0.172s

func TestA(t *testing.T) { t.Parallel(); time.Sleep(200 * time.Millisecond) }

func TestB(t *testing.T) {
    t.Parallel()
    // panic: testing: AllocsPerRun called during parallel test
    _ = testing.AllocsPerRun(10, func() { _ = make([]byte, 16) })
}

Покрытие: как считается и почему врёт

Go меряет покрытие операторов (statement coverage). При сборке с -cover исходник ещё до компилятора переписывается: каждая функция разбивается на базовые блоки, и в начало каждого блока вставляется инкремент счётчика. В конце прогона счётчики сериализуются в профиль. Отсюда режимы:

$ go test -covermode=atomic -coverpkg=./... -coverprofile=cover.out ./...
$ go tool cover -func=cover.out | tail -1        # итоговый процент
$ go tool cover -html=cover.out -o cover.html    # построчная раскраска
$ go build -cover -o app ./cmd/app               # Go 1.20+: покрытие обычного бинаря
$ mkdir -p /tmp/cov                              # каталог должен существовать заранее
$ GOCOVERDIR=/tmp/cov ./app                      # прогнали e2e, собрали счётчики
$ go tool covdata percent -i=/tmp/cov

testify: assert vs require

Разница ровно одна: assert.X при провале зовёт t.Errorf и возвращает false, тест продолжается. require.X зовёт t.FailNow() (по сути runtime.Goexit()), и тест обрывается на этой строке.

func TestGetUser(t *testing.T) {
    u, err := svc.Get(ctx, 42)

    require.NoError(t, err)   // без этого проверки ниже упадут на nil pointer dereference
    require.NotNil(t, u)      // предусловие: дальше без объекта смысла нет

    assert.Equal(t, "gopher", u.Login)   // а это независимые проверки:
    assert.Equal(t, 42, u.ID)            // хотим увидеть все расхождения за один прогон
    assert.True(t, u.Active)
}

У противоположного лагеря своя позиция: команда Go и большая часть стандартной библиотеки принципиально обходятся без testify и пишут if got != want { t.Errorf(...) } плюс cmp.Diff для структур. Аргументы: нет магии в стектрейсах, сообщение об ошибке пишет автор теста, порядок аргументов в assert.Equal(t, want, got) постоянно путают местами. На собесе полезно назвать оба подхода и сказать, что важнее единообразие внутри репозитория.

Время, случайность, конкурентность: три источника недетерминизма

Тест обязан быть функцией от входа. Всё, что приходит «из внешнего мира» (time.Now(), rand, планировщик горутин), надо либо инжектировать, либо накрыть детерминированной синхронизацией.

Время: инъекция часов

// Узкий интерфейс: столько методов, сколько реально нужно коду.
type Clock interface {
    Now() time.Time
}

type realClock struct{}
func (realClock) Now() time.Time { return time.Now() }

type Session struct {
    clock Clock
    ttl   time.Duration
}

func (s *Session) Expired(issuedAt time.Time) bool {
    return s.clock.Now().Sub(issuedAt) > s.ttl
}

// --- в тесте ---
type fakeClock struct {
    mu  sync.Mutex
    now time.Time
}
func (f *fakeClock) Now() time.Time { f.mu.Lock(); defer f.mu.Unlock(); return f.now }
func (f *fakeClock) Advance(d time.Duration) { f.mu.Lock(); f.now = f.now.Add(d); f.mu.Unlock() }

func TestSessionExpired(t *testing.T) {
    start := time.Date(2025, 3, 1, 12, 0, 0, 0, time.UTC)
    clk := &fakeClock{now: start}
    s := &Session{clock: clk, ttl: 30 * time.Minute}

    if s.Expired(start) { t.Fatal("свежая сессия не должна протухнуть") }
    clk.Advance(31 * time.Minute)               // мгновенно, без единого Sleep
    if !s.Expired(start) { t.Fatal("через 31 минуту сессия обязана протухнуть") }
}

Готовые реализации: github.com/benbjohnson/clock, k8s.io/utils/clock/testing (умеют фейковые таймеры и тикеры). Если код зависит от таймаута, делай таймаут параметром конфигурации, а не константой в теле функции: тест поставит 10 мс вместо 30 секунд.

// Go 1.25
func TestRetryBackoff(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        c := NewClient(WithBackoff(time.Second, 5))
        done := make(chan error, 1)
        go func() { done <- c.Do(context.Background()) }()

        // Пока тест ждёт результат, спят все горутины пузыря, и его часы
        // перескакивают через паузы бэкоффа: реально никто не ждёт.
        if err := <-done; err == nil {
            t.Fatal("ждали ошибку после исчерпания попыток")
        }
    })
}

// Go 1.27: synctest.Sleep поспит и дождётся, пока все успокоятся
func TestCacheTTL(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        c := NewCache(time.Minute)   // внутри фоновая горутина выкидывает протухшее по таймеру
        defer c.Close()              // без этого горутина переживёт тест, и Test упадёт с deadlock

        c.Set("k", "v")
        synctest.Sleep(time.Minute)  // ровно time.Sleep(time.Minute) + synctest.Wait()

        // уборщик проснулся от того же тика часов пузыря и уже отработал.
        // С голым time.Sleep порядок пробуждения двух горутин не определён, и тест флейкает.
        if _, ok := c.Get("k"); ok {
            t.Fatal("ключ должен был протухнуть")
        }
    })
}

Случайность

• Инжектируй источник: поле rnd *rand.Rand или интерфейс Shuffler. Тест получает rand.New(rand.NewSource(42)) с детерминированной последовательностью.
• Глобальный math/rand с Go 1.20 сам засеивается случайно при старте (rand.Seed объявлен устаревшим, а с Go 1.24 вообще ничего не делает), так что «зафиксировать seed глобально» больше не вариант. В math/rand/v2 (Go 1.22) функции Seed нет вовсе.
• crypto/rand подменяется через io.Reader-параметр: io.ReadFull(r, buf) в своём коде, а в тесте bytes.Reader с фиксированными байтами. В стандартных crypto-пакетах с Go 1.26 часть функций (генерация ключей RSA и ECDSA, подпись ECDSA) такой параметр игнорирует, для них есть testing/cryptotest.SetGlobalRandom.
• Если нужна именно случайность, это уже property-based подход: фаззинг (см. ниже) либо testing/quick (заморожен, но рабочий).

Конкурентность

• -race обязателен в CI. Детектор ловит только те гонки, которые реально произошли в этом прогоне. Стоит он замедления в 2–20 раз и роста памяти, зато ложных срабатываний почти нет. Отсюда практика: go test -race -count=5 ./... ночью.
• Никаких time.Sleep для «подождать, пока горутина доработает». На загруженном CI-раннере Sleep даёт флак, на свободном теряет секунды. Синхронизируй каналом, sync.WaitGroup или errgroup.
• Любое ожидание в тесте ограничивай таймаутом: select { case <-done: case <-time.After(2*time.Second): t.Fatal("таймаут") }. Без этого упавший тест вешает весь бинарь до -timeout, а потом печатает дамп всех горутин.
• -cpu=1,4 прогоняет тест при разных GOMAXPROCS — иногда вылезают сценарии, невидимые на одном ядре.

Golden files и фикстуры

Golden file («эталон») берут, когда ожидаемый результат не влезает литералом в код: отрендеренный HTML, сгенерированный SQL, JSON-ответ API, форматированный отчёт. Эталон лежит рядом в testdata/, тест сравнивает выход с файлом, а флаг -update перезаписывает эталон.

var update = flag.Bool("update", false, "перезаписать golden-файлы")

func TestRenderInvoice(t *testing.T) {
    got := Render(fixtureInvoice(t))
    golden := filepath.Join("testdata", "invoice.golden.json")

    if *update {
        if err := os.WriteFile(golden, got, 0o644); err != nil { t.Fatal(err) }
    }
    want, err := os.ReadFile(golden)
    if err != nil { t.Fatal(err) }

    if diff := cmp.Diff(string(want), string(got)); diff != "" {
        t.Errorf("рендер разошёлся с эталоном (-want +got):\n%s", diff)
    }
}

$ go test ./render -run TestRenderInvoice -update
$ git diff render/testdata/     # обязательный шаг: глазами посмотреть, что изменилось

Фикстуры описывают входные данные. Подходов два: файлы в testdata/ (JSON-пейлоады, SQL-дампы, примеры протокола) и билдеры в коде — функция-конструктор с валидным объектом по умолчанию и точечными правками. Билдеры почти всегда лучше: тест читается как «валидный заказ, но со скидкой 100 %», а не «двадцать полей, из которых важно одно». Общий глобальный набор фикстур на весь пакет считается антипаттерном: он связывает тесты друг с другом, и через год никто не знает, кто на какое поле опирается.

Fuzzing: тесты, которые придумывают вход сами

С Go 1.18 фаззинг встроен в go test. Пишется цель FuzzXxx(f *testing.F), а в ней семена через f.Add и сама проверка через f.Fuzz. Движок coverage-guided: он мутирует байты входа, следит за счётчиками покрытия и оставляет в корпусе те входы, которые открыли новый код. Поэтому фаззинг и не сводится к «случайным данным»: он целенаправленно лезет вглубь.

func FuzzParseRange(f *testing.F) {
    // Семенной корпус: реальные примеры и заведомо злые.
    f.Add("bytes=0-499")
    f.Add("bytes=-1")
    f.Add("")
    f.Add("bytes=9223372036854775807-9223372036854775807")

    f.Fuzz(func(t *testing.T, in string) {
        r, err := ParseRange(in)
        if err != nil {
            return               // отказать на мусоре можно, паниковать нельзя
        }
        // Эти свойства должны выполняться для любого принятого входа:
        if r.Start < 0 || r.End < r.Start {
            t.Fatalf("ParseRange(%q) вернул некорректный диапазон %+v", in, r)
        }
        // Round-trip: разобрали, собрали обратно, снова разобрали, результат тот же.
        again, err := ParseRange(r.String())
        if err != nil || again != r {
            t.Fatalf("round-trip сломался: %q -> %+v -> %q", in, r, r.String())
        }
    })
}

Запускается фаззинг отдельным флагом и только по одной цели за прогон — движку нужен весь процесс целиком:

$ go test ./httpx -run '^$' -fuzz FuzzParseRange -fuzztime 60s
fuzz: elapsed: 0s, gathering baseline coverage: 0/4 completed
fuzz: elapsed: 0s, gathering baseline coverage: 4/4 completed, now fuzzing with 14 workers
fuzz: minimizing 72-byte failing input file
fuzz: elapsed: 0s, minimizing
--- FAIL: FuzzParseRange (0.11s)
    --- FAIL: FuzzParseRange (0.00s)
        range_test.go:19: ParseRange("bytes=10-0") вернул некорректный диапазон bytes=10-0

    Failing input written to testdata/fuzz/FuzzParseRange/c55933f636ba0316
    To re-run:
    go test -run=FuzzParseRange/c55933f636ba0316
FAIL
exit status 1
FAIL	app/httpx	0.303s

$ go test ./httpx                 # найденный вход теперь прогоняется как обычный кейс

Корпусов у фаззера два. Семенной складывается из f.Add в коде и файлов в testdata/fuzz/FuzzXxx/; он лежит в репозитории и прогоняется при обычном go test, без всякого -fuzz. Сгенерированный корпус живёт в кеше сборки ($GOCACHE/fuzz), в git не попадает и между машинами не переносится. Найдя падение, фаззер минимизирует вход и записывает его в testdata/fuzz/. Этот файл надо закоммитить, и краш превратится в постоянный регрессионный тест.

func mustUser(t *testing.T, id int) User {
    t.Helper()                      // без этой строки отчёт покажет строку с t.Fatal ниже,
    u, err := repo.Get(ctx, id)     // а не строку вызова mustUser в самом тесте
    if err != nil {
        t.Fatalf("mustUser(%d): %v", id, err)
    }
    return u
}

func TestValidateUser(t *testing.T) {
    valid := User{Login: "gopher", Email: "g@example.com", Age: 30}

    tests := []struct {
        name    string
        mutate  func(*User)          // точечная правка валидного объекта
        wantErr error                // nil = ожидаем успех
        wantField string
    }{
        {name: "валидный пользователь", mutate: func(*User) {}},
        {name: "пустой логин",  mutate: func(u *User) { u.Login = "" },
            wantErr: ErrRequired, wantField: "login"},
        {name: "логин 1 символ", mutate: func(u *User) { u.Login = "a" },
            wantErr: ErrTooShort, wantField: "login"},
        {name: "логин на границе 2", mutate: func(u *User) { u.Login = "ab" }},
        {name: "email без собаки", mutate: func(u *User) { u.Email = "gopher.example.com" },
            wantErr: ErrFormat, wantField: "email"},
        {name: "отрицательный возраст", mutate: func(u *User) { u.Age = -1 },
            wantErr: ErrRange, wantField: "age"},
        {name: "юникод в логине", mutate: func(u *User) { u.Login = "гофер" }},
    }

    for _, tc := range tests {
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            u := valid          // своя копия на каждый кейс, общего состояния нет
            tc.mutate(&u)

            err := ValidateUser(u)

            if tc.wantErr == nil {
                if err != nil {
                    t.Fatalf("ожидали успех, получили %v", err)
                }
                return
            }
            if !errors.Is(err, tc.wantErr) {          // не reflect.DeepEqual и не сравнение строк
                t.Fatalf("ожидали %v, получили %v", tc.wantErr, err)
            }
            var ve *ValidationError
            if errors.As(err, &ve) && ve.Field != tc.wantField {
                t.Errorf("поле: got %q, want %q", ve.Field, tc.wantField)
            }
        })
    }
}

// До Go 1.22 классический баг: все подтесты видят последний tc
for _, tc := range tests {
    t.Run(tc.name, func(t *testing.T) {
        t.Parallel()             // тест паркуется; цикл успевает докрутиться до конца
        check(tc.input)          // tc одна на весь цикл, к моменту старта в ней последний кейс
    })
}

// До 1.22 лечилось так:
for _, tc := range tests {
    tc := tc                     // копия на итерацию (или параметр функции)
    t.Run(tc.name, func(t *testing.T) { t.Parallel(); check(tc.input) })
}

u, err := svc.Get(ctx, 42)
require.NoError(t, err)              // без этого проверки ниже упадут на nil pointer dereference
require.NotNil(t, u)

assert.Equal(t, "gopher", u.Login)   // независимые проверки: хотим весь список расхождений
assert.Equal(t, 42, u.ID)
assert.True(t, u.Active)

type Clock interface {
    Now() time.Time
    After(d time.Duration) <-chan time.Time
}

type realClock struct{}
func (realClock) Now() time.Time { return time.Now() }
func (realClock) After(d time.Duration) <-chan time.Time { return time.After(d) }

type fakeClock struct {
    mu  sync.Mutex
    now time.Time
    waiters []chan time.Time     // «спящих» будим вручную
}
func (c *fakeClock) Advance(d time.Duration) { /* двигаем now и будим тех, чей дедлайн прошёл */ }

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

Вопрос «как замокать базу» на собесе почти никогда не про библиотеку. Он про то, понимаешь ли ты, откуда вообще берётся точка подмены — а берётся она из того, где объявлен интерфейс. Потом разговор уходит в другую сторону: что моками нельзя проверить в принципе и когда честнее поднять настоящий PostgreSQL в контейнере.

Сначала — пять слов, которыми называют подделки

Тестируемый код лезет в базу, в платёжный шлюз и в 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. Директиву обычно кладут прямо рядом с интерфейсом:

//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); ... }   // точечно