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

После пятнадцатого урока у нас на руках полный протокол честности для ошибок: обёртка с %w, errors.Is и errors.As. Осталось сделать последний шаг — перестать проверять эти обещания вручную. До сих пор мы убеждались, что функция работает, запуская go run и глядя на печать глазами. Это работает ровно до того дня, когда правка в одной функции ломает три другие, а вы узнаёте об этом от пользователя. Тест — та же проверка, только записанная кодом: она не устаёт, не пропускает и её можно запустить тысячу раз за день.

По запросу «тестирование go» новичок обычно ищет, какой фреймворк поставить. Ответ разочаровывает своей простотой: ничего ставить не нужно. В языке есть пакет testing, у команды go есть подкоманда go test, а конвенция одна: тесты живут в файлах с суффиксом _test.go рядом с проверяемым кодом. Никаких assert-функций тоже нет — тест просто делает if и в ветке «не совпало» зовёт t.Errorf или t.Fatalf. Звучит примитивно, но именно эта примитивность сделала го-тесты легендарно читаемыми: тест — обычный код, без магии, и пишется за минуту.

Что будет в уроке. Сначала контракт: файл _test.go, сигнатура func TestXxx(t testing.T), что go build игнорирует, а go test — компилирует и запускает. Потом различие, которое путают все: t.Error — «пометить провал и продолжить», t.Fatal — «пометить провал и выйти» (разница в runtime.Goexit, разберём до буквы). Затем главная идиома — table driven tests: срез структур с ожиданиями, цикл и t.Run для под-тестов; по этой схеме написано большинство тестов в самой стандартной библиотеке. После неё — инструменты вокруг: t.Helper для честных номеров строк, t.Skip для честного «не сегодня», t.Cleanup для уборки, t.Parallel для параллельности. Финишь — покрытие: go test -cover покажет, какие строки ваш прогон так и не потревожил.

Одна оговорка заранее, чтобы дальше не отвлекаться. Запуск тестов — это работа настоящего go test: он собирает пакет с тестовым файлом, находит Test-функции и прогоняет каждую в своей горутине. Ни резервный, ни основной движок песочницы этого не делают (первый пакет testing вообще не знает, у второго нет команды test), поэтому Test-функции урока — листинги для чтения и локального запуска, а интерактивы гоняют тестируемый код и мини-эмуляции семантики Error/Fatal. Честнее не придумаешь: смотрите на настоящие тесты и тут же трогаете руками их логику.

Контракт тестирования в Go держится на трёх правилах, и все три проверяет сам go test. Правило первое — файл: тесты кладут рядом с кодом, в файл, имя которого кончается на _test.go — phone.go и phone_test.go лежат в одном каталоге и одном пакете. Команда go build при сборке программы все *_test.go молча пропускает: тесты не попадают в бинарник и не утяжеляют поставку. Команда go test — наоборот: собирает пакет вместе с тестовыми файлами и запускает найденные тесты. Один и тот же каталог, два режима, нулевая настройка.

Правило второе — имя. Тест — это функция с префиксом Test и продолжением с заглавной буквы: TestAdd, TestNormalizePhone, TestParseDuration. Продолжение после Test обязано начинаться с прописной буквы — testadd не считается, компилятор пакетов тестов молча не увидит такую функцию. Через имена вы директивно отбираете, что прогонять: go test -run TestNormalize запустит только совпавшие с шаблоном тесты. Это делает имена маленьким API отчёта — по ним вы потом ищете провал в сотне зелёных строк.

Правило третье — сигнатура: func TestXxx(t *testing.T). Один параметр — указатель на testing.T, «руль» теста: через него тест сообщает о провале (t.Error, t.Fatal), печатает заметки (t.Log), заводит под-тесты (t.Run) и регистрирует уборку (t.Cleanup). Возвращать тест ничего не должен — результат выражается не return, а вызовами на t: тест без ни одного такого вызова считается пройденным. Отсюда и стиль сообщений: го-тесты не «упали с исключением», а аккуратно перечислили, что получили и что ждали — «Add(2, 3) = 4; want 5».

Как это выглядит на командной строке (всё — текстом, запуск локальный). go test в каталоге пакета прогоняет его тесты и печатает одну строку: ok example.com/phone 0.312s — пакет собрался, тесты прошли. Провал выглядит как: --- FAIL: TestAdd (0.00s), ниже — файл:строка и ваше сообщение, в конце FAIL example.com/phone. Флаг ./... разгоняет прогон на весь проект: go test ./... обходит все пакеты от текущего каталога вниз — именно эту команду вы будете запускать после каждой правки. Флаг -v (verbose) добавляет построчный рассказ: === RUN TestAdd, --- PASS: TestAdd, и то же самое с отступом для каждого под-теста. Без -v успешный тест молчит — шумят только провалы; правило отчётности то же, что у t.Log: молчи, пока здоров.

Вот здесь спотыкаются почти все, кто приходит из языков с assert. В Go два режима провала, и выбирать нужно осознанно. t.Error (и t.Errorf с форматированием) помечает тест проваленным и продолжает выполнение: следующие проверки тоже отработают, и вы получите полный список расхождений за один прогон. t.Fatal (и t.Fatalf) сначала помечает провал, а затем останавливает тест — выполняется как «Log + FailNow», а FailNow внутри зовёт runtime.Goexit: горутина теста аккуратно завершается, все defer в ней отрабатывают, но код после вызова уже не исполняется.

Выбор между ними — вопрос здравого смысла про «есть ли смысл жить дальше». Проверяете поля структуры — t.Errorf: пусть отчёт покажет все несоответствия разом. А если Split(in) вернул ошибку или nil, и следующие строки обязаны разыменовывать результат — только t.Fatalf: продолжать нечем, каждая следующая строка лишь добавит панику к провалу. Правило: Fatal — когда продолжение не проверка, а падение; Error — когда вы собираете полный список претензий.

У Fatal есть два неочевидных следствия, о которых честно предупреждает документация пакета testing. Первое: FatalNow-семантика убивает только ТЕКУЩУЮ тест-функцию (или под-тест), а не прогон: соседние кейсы таблицы выполнятся, родительский тест продолжит цикл, следующие Test-функции запустятся как ни в чём не бывало. Именно поэтому Fatal безопасен в цикле табличного теста: один сломанный кейс не топит остальных — их вердикты вы всё равно увидите. Второе: FailNow обязан вызываться из той горутины, которая выполняет тест. Если проверки делает фоновая горутина, созданная тестом, — там доступен только t.Error (и t.Error обязан), потому что Goexit в чужой горутине не остановит тест, а просто тихо убьёт её.

Младшие братья, чтобы картина была полной. t.Log и t.Logf — заметка в отчёт без провала: печатается, только если тест провалился или запущен с -v. t.Fail — пометить провал без выхода, лысая пара к t.Error без аргументов. t.FailNow — сам выход без записи сообщения (почти всегда вам нужен Fatal, а не голый FailNow). И обратите внимание на симметрию Skip-семейства, которая скоро понадобится: t.Skip определён как «Log + SkipNow», где SkipNow — тот же runtime.Goexit, только тест помечается не проваленным, а пропущенным.

Первая проверка Add выглядела невинно, но у неё есть экспоненциальная болезнь: на каждый новый вход — новый блок if, новый got и want, новая строка шума. Десять проверок — десять почти одинаковых кусков кода, отличающихся только данными. А данные — это и есть тест. Отсюда идиома, которой пропитана вся экосистема, включая стандартную библиотеку: table driven tests — табличные тесты. Ожидания складываются в срез структур, а единственный цикл прогоняет все кейсы одним каркасом проверки. Вики-страница go.dev/wiki/TableDrivenTests описывает её в трёх строках: определяете структуру кейса, заполняете срез, итерируете с t.Run.

Структура кейса — зеркало того, что вы проверяете. Поле name — человеческое имя кейса, которое попадёт в отчёт и в имя под-теста (без него провал пятого кейса из семи скажет вам только «пятой не понял»). Поля входа — in, сырые аргументы. Поля ожиданий — want и его родственники: wantErr, wantLen, wantCode — по конвенции всё, что начинается с want. Булево wantErr — классика для функций, возвращающих (значение, error): true значит «здесь мы ждём отказ», и тогда проверяется сама ошибка (сквозь errors.Is — пятнадцатый урок как раз об этом), а не значение.

Второй столп идиомы — цикл с t.Run(name, func(t *testing.T) {...}): каждый кейс становится под-тестом со своим именем, своим вердиктом и своим журналом. Провал одного кейса не мешает остальным (Fatal выходит только из под-теста), отчёт -v перечисляет кейсы по именам, а флаг -run умеет выбирать одиночный кейс по имени — с копипастой так не умеет никто. Табличный тест масштабируется бесплатно: добавить поведение — значит добавить строку данных, не трогая логику проверки.

Одна тонкость, о которой стоит знать заранее: захват переменной цикла. Исторически (до Go 1.22) переменная tt из for _, tt := range была одна на весь цикл, и в замыкании под-теста к моменту выполнения она могла показывать уже следующий кейс — лечилось теневой копией tt := tt первой строкой замыкания. Начиная с Go 1.22 (при go 1.22 и выше в go.mod) переменная итерации своя на каждую итерацию, и подтенение не нужно; встречая tt := tt в старом коде, вы теперь знаете, чей это шрам. В наших листингах go.mod modern — копии не заводим.

t.Run(name, f) — команда, из-за которой табличные тесты стали стандартом. Механика: Run заводит под-тест с именем name, выполняет f в ОТДЕЛЬНОЙ горутине и блокируется до её завершения; возвращает булево «под-тест удался» (даже если он вышел через t.Skip — Skip считается успехом прогона). Имена складываются в путь через слэш: TestNormalizePhone/городской — так отчёт и флаги различают глубину. Под-тесты можно вкладывать: t.Run внутри под-теста даст TestX/слой1/слой2 — иерархию любой глубины, хотя чаще хватает двух уровней «тест/кейс».

Отдельная прелесть имён — фильтрация. go test -run TestNormalizePhone запускает только этот тест; go test -run 'TestNormalizePhone/городск' — только кейсы, чьё имя содержит «городск»: регулярное выражение применяется сначала к имени теста, затем к имени под-теста. Нюанс, о котором документация предупреждает честно: пробелы в именах под-тестов прогон заменяет на подчёркивания — кейс «с восьмёркой» в отчёте выглядит как TestNormalizePhone/с_восьмёркой, и фильтр нужно писать по подчёркнутой форме. По этой причине многие команды пишут имена кейсов без пробелов заранее.

t.Parallel — обещание «этот под-тест (или тест) можно выполнять параллельно с другими Parallel». Вызов t.Parallel() внутри t.Run останавливает под-тест в специальной точке: сначала выполняется ВСЯ последовательная часть родителя (цикл по кейсам проходит целиком, регистрируя параллельные под-тесты), и только когда родительская функция закончилась, припаркованные под-тесты просыпаются и бегут одновременно — параллельно только друг с другом и другими Parallel, не со всем подряд. Отсюда два практических правила: ресурсы, которые трогает параллельный под-тест, не должны делить изменяемое состояние без синхронизации (мьютексы из восьмого урока вам в помощь), и замыкание должно захватывать свой tt — в современном Go это бесплатно, а в до-1.22 требовало теневой копии. Флаг -count и переменные -cpu умножают прогоны: тест, помеченный Parallel, при этом не параллелится сам с собой — одинаковые копии идут по очереди.

Провал в отчёте указывает файл и строку — но какую? Сначала сделаем боль видимой. Пусть несколько тестов делят общий хелпер:

func requirePositive(t *testing.T, got int) { if got <= 0 { t.Errorf("ожидали положительное, получено %d", got) } }

Провал укажет на строку с t.Errorf — на хелпер, который одинаков для всех вызовов. Пять тестов зовут его — пять отчётов показывают одну и ту же строку, и искать виновника приходится вручную. t.Helper() решает это одной строкой: вызовите его первой строкой хелпера — и фреймворк исключит его из отчёта о позиции; строка и файл укажут на ТЕСТИРОВАЕМЫЙ код вызова, то есть на то место, которое вы реально будете править.

Тонкость, которую стоит прочувствовать: t.Helper не меняет ничего в логике — ни провалов, ни остановок; он меняет только бухгалтерию отчёта (и только если хелпер принимает *testing.T — иначе ему нечем отчитываться). Поэтому конвенция такая: хелпер, вызывающий t.Error/t.Fatal, обязан принимать t параметром (не глобально!) и начинаться с t.Helper(). Встречали в этом уроке табличную идиому? t.Run решает ту же задачу с другой стороны: имя кейса само делает отчёт точным. Helper нужен там, где таблица не подходит — разрозненные проверки, общие приспособления, шаги «подготовь-провери-убери».

Не всякий тест обязан бежать всегда. Тест интеграции с платёжным шлюзом — без ключей из окружения; тест под Windows — под Windows; тест длинного сценария — в ночном прогоне. Для таких случаев у t есть семейство Skip: t.Skip("нет ключей шлюза") печатает причину и останавливает тест через runtime.Goexit — тот же механизм, что у Fatal, но тест помечается не провалом, а пропуском. В отчёте -v это отдельный вердикт: --- SKIP: TestPayments (0.00s) с вашей причиной ниже; общий итог пакета остаётся ok — пропуск не красит прогон в красный.

Почему не просто return? Обычный return из теста молча засчитывает ПАСС: отчёт покажет зелёный тест, который на самом деле не проверил ничего. Skip — это честность: «проверки не было, вот почему». Разница между «прошёл» и «пропущен» — разница между «работает» и «не знаю»; в большом проекте второе хотя бы не врёт. t.Skipf даёт то же с форматированием: t.Skipf("пропуск: %v", err).

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

Тесты заводят ресурсы: временный файл, каталог с фикстурой, соединение с тестовой базой, сервер на localhost. Убирать за собой нужно в любом исходе — прошли, провалились, вышли через Fatal. Для этого у t есть t.Cleanup(f func()): регистрирует функцию, которую фреймворк вызовет, когда тест (и все его под-тесты) завершатся — в обратном порядке регистрации, LIFO, ровно как defer из второго урока. Ключевое отличие от defer внутри теста: Cleanup, зарегистрированный в хелпере, сработает для вызывающего теста — функция-помощник может сама и создать ресурс, и записать его уборку, а тест об этом даже не вспомнит. И Cleanup срабатывает на любом исходе, включая провал и Goexit: Fatal посреди теста уборку не отменяет.

Порядок стоит запомнить буквально: регистрации разгружаются в обратном порядке — последний созданный ресурс закрывается первым. Если ресурсу нужен контекст, который живёт ровно столько, сколько тест, — из девятого урока вы знаете, что контекст отменяют явно; с Go 1.24 у t появился и t.Context(): контекст, который отменяется автоматически перед вызовом функций Cleanup. Для старых версий связка «ctx, cancel := context.WithCancel(...); t.Cleanup(cancel)» делает то же самое руками.

Когда что выбирать — правило одной строки. Уборка, привязанная к куску кода в той же функции, — defer (читается прямо на месте). Уборка, которую хелпер обязан вернуть вызывающему, — t.Cleanup. А если тест внезапно переусложнился уборкой — это обычно сигнал, что проверяется слишком много: часть приспособлений просится в отдельную функцию с t.Helper и t.Cleanup внутри.

Тесты прошли — но какие строки они вообще трогали? На этот вопрос отвечает покрытие. go test -cover прогоняет тесты с инструментацией и дописывает к итогу пакета процент: ok example.com/phone 0.312s coverage: 92.3% of statements. Считаются ВЫПОЛНЕННЫЕ операторы: доля строк кода, через которые хоть раз прошёл хотя бы один ваш тест. Возьмите табличный тест NormalizePhone и уберите кейс «пустая строка» — процент проседает: ветка «нет ни одной цифры» осталась непройденной, и покрытие нашло дыру за вас.

Два уровня детализации поверх процента. go test -coverprofile=cover.out сохраняет пооператорную карту в файл, а go tool cover -func=cover.out печатает процент по каждой функции — мгновенно видно, что NormalizePhone покрыт на сто, а вспомогательный parseNote — на тридцать. go tool cover -html=cover.out открывает в браузере листинги пакета: зелёное — покрыто, красное — не тронуто. Красные строки в go-коде — это почти всегда недостающие кейсы таблицы; смотреть такой отчёт перед релизом полезнее любого чек-листа.

И обязательная оговорка, чтобы метрика не стала культом. Покрытие меряет «код исполнялся», а не «код проверен». Тест, который вызвал функцию и не сравнил результат, поднимает процент, не поймав ни одной ошибки; тест с неверным want — тоже. Стопроцентное покрытие гарантирует только одно: нет строк, которые прогон не исполнял, — но не то, что каждое исполнение что-то утверждал. Отсюда рабочая норма: покрытие — инструмент поиска дыр (куда добавить кейсы), а не целевая функция (набить 100 любой ценой). Дыры ищите там, где деньги: ветки ошибок, границы диапазонов, парсеры.

Соберём урок в одну картину. Тест в Go — обычная функция func TestXxx(t testing.T) в файле _test.go: go build её игнорирует, go test — компилирует и зовёт. Провал выражается двумя режимами: t.Error помечает и продолжает, t.Fatal помечает и выходит через runtime.Goexit — без выноса соседних кейсов и родителя. Главная идиома — table driven tests: срез структур с name/in/want/wantErr, один цикл и t.Run, дающий каждому кейсу имя, горутину и изолированный вердикт. Вокруг — сервисные ручки: t.Helper возвращает отчёту честные номера строк, t.Skip фиксирует честное «не сегодня», t.Cleanup убирает ресурсы в LIFO-порядке при любом исходе, t.Parallel разгоняет независимые кейсы. И метрика здоровья — покрытие go test -cover: инструмент поиска непройденных веток, но не гарантия осмысленных проверок.

Естественный вопрос после «правильно ли» — «а насколько быстро?». Тест на 50 миллисекунд и тест на 5 секунд проходят одинаково зелёно, а разница между ними — вся ваша латентность. Для ответа в стандартной библиотеке есть второй инструментарий того же семейства: бенчмарки func BenchmarkXxx(b *testing.B) с циклом по b.N, флаг -benchmem и профилировщик pprof, который покажет, на что ушла секунда. Семнадцатый урок разберёт их целиком: как b.N подгоняет число итераций, как читать ns/op и B/allocs, и как профиль превращает подозрения в факты. Проверка поведения и измерение скорости — две половины одного навыка; сегодня была первая.

До встречи на странице курса: а если захочется освежить, на чём стоят сегодняшние проверки, — вернитесь к уроку про оборачивание ошибок и перечитайте sentinel-раздел: errors.Is в табличных кейсах с wantErr теперь ваш ежедневный инструмент.