Механика

go test компилирует пакет вместе с _test.go-файлами и генерирует _testmain.go со списком найденных тестов. Рефлексии в рантайме нет, поэтому динамически тест регистрируется только через t.Run. Имя ищется по префиксу Test + не-строчная буква: func Testfoo не запустится (с Go 1.24 на это ругнётся vet-анализатор tests, который go test гоняет сам). Каждый тест выполняется в своей горутине, и отсюда главное правило: t.Fatal внутри вызывает runtime.Goexit() и завершает горутину теста. Позвал t.Fatal из побочной горутины - убил её, а тест поехал дальше и, скорее всего, упал паникой строчкой ниже. Из побочных горутин можно только t.Error.

t.Run - сабтесты

t.Run(name, func(t *testing.T)) создаёт дочерний *testing.T и по умолчанию блокируется до его завершения (если только ребёнок не позвал t.Parallel). Что это даёт:

• Изоляция провала: t.Fatal в сабтесте обрывает только его, остальные кейсы таблицы отработают.
• Фильтрация: в go test -run 'TestValidate/пустой_email' флаг -run принимает имена через /, по уровням вложенности. Пробелы в имени заменяются на _, дубликаты получают суффикс #01.
• Общий setup: код до первого t.Run выполняется один раз на всю группу.

t.Helper

Вызов t.Helper() в первой строке функции помечает её как вспомогательную. При провале testing идёт вверх по стеку и печатает первую строку, которая не помечена хелпером. Без этого все ошибки показывают одну и ту же строку внутри assertUser, и непонятно, какой из двадцати вызовов сломался. Пометка хранится на самом *testing.T, а не на горутине, поэтому она действует и когда хелпер зовут из побочной горутины: отчёт всё равно покажет строку вызова, а не строку внутри хелпера. Толку от этого, правда, немного - «строкой вызова» там окажется тело go func().

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
}

t.Cleanup vs defer

t.Cleanup(f) кладёт f в стек (LIFO) конкретного *testing.T и вызывает его, когда этот тест и все его подтесты, включая параллельные, завершились. Разница с defer принципиальна в двух местах:

• Хелперы: defer внутри setupDB(t) сработает при выходе из setupDB, то есть до начала самого теста, а t.Cleanup после него. Поэтому фабрики ресурсов пишут именно через Cleanup.
• Параллельные подтесты: defer в родителе выполняется, когда родитель вернул управление, - а параллельные дети в этот момент ещё не начинались. Отсюда баг «база закрыта, тест падает». t.Cleanup родителя ждёт всех детей.

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)
            }
        })
    }
}

Как организуют негативные кейсы

• Мутация валидного объекта, а не двадцать литералов целиком. Тогда в кейсе видно ровно то, что его отличает, и новое обязательное поле не ломает всю таблицу.
• Ожидаем сентинель или тип, а не строку. Сравнение err.Error() == "..." привязывает тест к формулировке сообщения; поменяли текст - упало двадцать тестов. errors.Is переживает оборачивание через %w.
• Границы отдельными кейсами: длина 1 / 2 / 3 при минимуме 2, возраст 0 / -1, пустая строка / пробелы / юникод / очень длинная строка.
• Валидатору, собирающему все ошибки сразу, нужна отдельная группа кейсов: проверяем, что при трёх плохих полях вернулось три ошибки, и что errors.Is находит каждую (в Go 1.20+ это errors.Join).
• Когда кейсов на один вход набираются сотни, пора переходить к фаззингу, а не растить таблицу на 400 строк.

Что происходит по шагам

1. Тест зовёт t.Parallel(), метод сигналит родителю и блокируется на канале. Функция теста останавливается ровно на этой строке.
2. Родитель (или tRunner верхнего уровня) продолжает: запускает следующий t.Run, тот тоже паркуется, и так далее.
3. Когда тело родителя закончилось, testing разблокирует всех припаркованных детей сразу, но одновременно бегут не больше -parallel, остальные ждут в очереди.
4. Родитель не завершается, пока не отработают все параллельные дети; его t.Cleanup выполнится после них, а defer уже выполнился до их старта.

Отсюда два следствия, которые и спрашивают. Первое: вызов t.Parallel() должен идти первой строкой подтеста - код до него исполняется последовательно и в другой момент времени. Второе: параллелятся тесты внутри одного пакета; разные пакеты и так идут параллельно (флаг -p, по умолчанию GOMAXPROCS), это независимые процессы.

Ловушка с переменной цикла

// До 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) })
}

В Go 1.22 семантику изменили: при go-директиве в go.mod не ниже 1.22 переменные for-цикла создаются заново на каждой итерации, и строка tc := tc больше не нужна (линтер copyloopvar и модернизаторы gopls подсвечивают её как лишнюю). Решает при этом версия в go.mod, а не версия компилятора: старый модуль с go 1.19, собранный новым тулчейном, работает по-старому. И баг проявлялся именно из-за парковки: без t.Parallel замыкание выполнялось сразу и видело правильное значение, поэтому «непараллельная» версия того же теста была зелёной.

Когда параллелить не стоит

• Глобальное состояние: переменные окружения (t.Setenv прямо паникует в параллельном тесте), рабочая директория, глобальные синглтоны, http.DefaultClient, подмена time.Now через пакетную переменную.
• Общая БД без изоляции: тесты видят чужие строки. Либо схема/транзакция на тест, либо последовательно.
• Тесты, чувствительные к времени и ресурсам: бенчмарки, замеры таймаутов, тесты с ограничением по памяти. Под нагрузкой соседей они флакают. С Go 1.25 один такой случай стал явной ошибкой: testing.AllocsPerRun паникует (AllocsPerRun called during parallel test), если в момент замера бежит параллельный тест - раньше это молча давало плавающее число аллокаций.
• Быстрые тесты чистых функций: накладные расходы на планировщик больше выигрыша, а риск словить скрытую связанность вполне реален. Параллелить осмысленно там, где тест ждёт: сеть, диск, контейнеры.

Как считается

При сборке с -cover инструмент cover переписывает исходник ещё до компилятора: режет каждую функцию на блоки и вставляет в начало блока инкремент счётчика. Режимы: set (был/не был, по умолчанию), count (сколько раз), atomic (атомарный инкремент; с -race он обязателен и ставится сам, иначе сам профилировщик стал бы источником гонки). -coverpkg=./... считает покрытие чужих пакетов, и тогда интеграционный тест из tests/ засчитывается в internal/. С Go 1.20 покрытие снимается и с обычного бинаря: go build -cover, затем GOCOVERDIR=... ./app и go tool covdata. До этого e2e-покрытие снимали обходным путём: тестовым бинарём с -coverpkg, в котором тест просто зовёт main().

Почему 100 % ничего не гарантируют

• Комбинации условий не видны. if a && b занимает одну строку: два теста закрывают её на 100 %, а из четырёх комбинаций проверены две.
• Границы не видны. i <= n против i < n - та же строка, тот же процент, другой результат.
• Отсутствующий код покрыть нельзя. Забытая проверка nil или необработанная ветка err не имеет строки, которая могла бы стать красной.
• Качество ассертов не учитывается. Тест, который вызвал функцию и ничего не проверил, даёт ровно те же проценты. Такие тесты и появляются, когда в KPI записан порог покрытия.
• Конкурентность. Гонка исполняет те же строки; покрытие про порядок ничего не знает.

Что отвечать про «хороший процент»

Что число зависит от слоя: доменная логика, парсеры, расчёты требуют 90 %+, там это дёшево и полезно; хендлерам и репозиториям хватает 60–80 %, выше начинается тестирование фреймворка; сгенерированный код, моки, DTO, main.go и обвязку миграций исключают из подсчёта. Полезнее абсолютного числа два правила: покрытие diff'а в PR (новый код покрыт) и покрытие не падает. А качество самих тестов проверяет мутационное тестирование (go-mutesting, gremlins): инструмент меняет > на >=, удаляет вызовы, и если тесты остались зелёными - покрытие было декоративным.

Правило выбора

require нужен для предусловий: если они провалились, остаток теста либо упадёт паникой, либо напечатает бессмысленный мусор. Типичные примеры: require.NoError(t, err), require.NotNil, require.Len перед индексацией слайса. На assert пишут независимые утверждения о результате, чтобы увидеть все расхождения за один прогон и не чинить их по одному. Тест целиком на require отдаёт по одной ошибке за запуск; тест целиком на assert падает nil-паникой на первой же неудаче.

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)

Три ловушки, на которых ловят

• require из побочной горутины. FailNow сводится к Goexit: он убьёт горутину, провал запишется, а тест пойдёт дальше и зависнет на WaitGroup, если Done вызывается не через defer. В горутинах пиши только assert.
• assert.Equal строг к типам: assert.Equal(t, 1, int64(1)) падает. Есть EqualValues, но надёжнее привести типы явно.
• assert.Nil ≠ assert.NoError: Nil работает через рефлексию и пройдёт для типизированного nil-указателя в интерфейсе, хотя в бою err != nil вернёт true. Для ошибок только NoError/ErrorIs/ErrorAs.

Время

Прямой вызов time.Now() внутри доменной логики делает её непроверяемой: тест «токен истёк через час» пришлось бы ждать час. Лечится это узким интерфейсом на стороне потребителя:

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 и будим тех, чей дедлайн прошёл */ }

Тогда тест «через 61 минуту токен протух» выполняется за микросекунды: clk.Advance(61 * time.Minute). Готовые реализации есть в k8s.io/utils/clock/testing и github.com/jonboulle/clockwork. В Go 1.23 переписали таймеры: Timer/Ticker, на которые не осталось ссылок, собираются GC даже без Stop, а канал стал небуферизованным, и часть старых трюков с time.After в тестах поменяла поведение. И ещё: time.Time содержит монотонную часть, поэтому reflect.DeepEqual на двух «одинаковых» временах может дать false. Сравнивают через .Equal() или cmpopts.EquateApproxTime.

Случайность

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

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

• Никакого time.Sleep для «подождать горутину»: на нагруженном раннере это флак, а в зелёном прогоне - потерянные секунды. Синхронизируют каналом, sync.WaitGroup или errgroup. Go 1.25 добавил wg.Go(func(){...}), который сам делает Add(1)/Done.
• Любое ожидание делают с таймаутом: select { case <-done: case <-time.After(2*time.Second): t.Fatal("таймаут") }. Иначе повисший тест держит весь бинарь до -timeout и печатает дамп всех горутин.
• -race в CI обязателен. Детектор находит только те гонки, которые реально произошли в этом прогоне, зато практически без ложных срабатываний. Отсюда практика go test -race -count=5 ./... ночью и -cpu=1,4 для разных GOMAXPROCS.
• Ассерты делают только из горутины теста; из побочных t.Fatal/require запрещены (это Goexit). Результаты собирают через канал.
• Утечки горутин ловит go.uber.org/goleak, подключённый одной строкой в TestMain.

Golden files

Применяют, когда ожидаемый результат слишком велик для литерала в коде: отрендеренный HTML, сгенерированный SQL, JSON-ответ API, форматированный отчёт, вывод CLI. Схема стандартная: с флагом -update файл перезаписывается, без него идёт сравнение через cmp.Diff, чтобы в отчёте был читаемый дифф, а не два блоба по 40 КБ. После -update обязательно просмотреть git diff testdata/ глазами, иначе golden-тест превращается в «сломал логику, перегенерировал, зелёно».

Почему именно testdata: эту директорию тулчейн Go игнорирует, не обходит по ./... и не компилирует, туда можно класть хоть заведомо битый Go-код. А поскольку тест запускается из директории пакета, testdata/x.json находится без runtime.Caller. //go:embed для эталонов хуже: содержимое вшивается на этапе сборки, и -update в том же прогоне уже ничего не изменит.

Как они гниют и что с этим делать

• Нестабильные поля: time.Now(), UUID, порядок обхода мапы, порядок элементов из БД без ORDER BY. Нормализуй перед сравнением: фиксированные часы, детерминированный генератор ID, явная сортировка. (json.Marshal сортирует ключи мапы, но не элементы слайса.)
• Формат в одну строку: дифф превращается в «строка 1 отличается». Храни эталон отформатированным построчно.
• Golden на две строки: если ожидание помещается в литерал, файл только прячет смысл. Оправдано от десятков строк.

Фикстуры

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

Чем отличается от «случайных данных»

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

Как устроено

• f.Add(...) задаёт семенной корпус в коде, файлы в testdata/fuzz/FuzzXxx/ хранят его в репозитории. Оба прогоняются при обычном go test, без -fuzz.
• f.Fuzz(func(t *testing.T, in string) {...}) объявляет саму цель. Типы аргументов ограничены: []byte, string, int*/uint*, float32/64, bool, rune, byte. Структуру фаззят через []byte с разбором внутри цели.
• Запуск: go test -run '^$' -fuzz FuzzXxx -fuzztime 60s ./pkg - одна цель за прогон. Сгенерированный корпус лежит в $GOCACHE/fuzz и в git не попадает.
• Падением считаются паника, t.Error/t.Fatal внутри цели, дедлок, срабатывание -race, os.Exit, таймаут воркера. Возвращённая функцией ошибка падением не считается: корректный отказ на мусоре нормален.

Что проверять внутри цели

Свойства, а не конкретные значения: «не паникует» (самая дешёвая и самая результативная проверка), round-trip (Parse(v.String()) == v), differential (своя быстрая реализация против эталонной или стандартной библиотеки), доменные инварианты (длина результата не больше входа, сумма сохранилась).

Когда полезен

Там, где вход приходит извне и представим как байты: парсеры и декодеры, свои DSL, разбор заголовков и URL, санитайзеры, форматы файлов, всё вокруг безопасности. Бизнес-логика с десятком доменных структур фаззится плохо - кода на генерацию входа больше, чем самой проверки, и почти всё отсекается валидацией на первой строке. В CI фаззинг ставят отдельным ночным job'ом с -fuzztime: он занимает все ядра и по своей природе не завершается сам. Цель обязана быть детерминированной и без побочных эффектов - воркеров несколько.