Тестирование приложений: httptest, e.ServeHTTP и table-driven матрицы

Тема «тестирование echo» начинается с выбора уровня, и он важнее выбора библиотеки. Первый уровень — тест хендлера или middleware напрямую: контекст собирается через e.NewContext(req, rec), функция вызывается руками, роутер и глобальные слои не участвуют. Это юнит-тест: быстрый, точечный, он проверяет логику функции, а не проводку. Второй уровень — тест всего стека: e.ServeHTTP(rec, req) прогоняет запрос как настоящий сервер — по пулу контекстов, через роутер, applyMiddleware с глобальными middleware и HTTPErrorHandler на исходящих ошибках. Это интеграционный тест вашего HTTP-слоя: он ловит то, что юнит-тест не увидит — забытый маршрут, неправильный порядок слоёв, отказ, который не дошёл до конверта {error, code}.

Оба уровня опираются на одну пару из net/http/httptest — пакета стандартной библиотеки, написанного именно для этого. httptest.NewRequest собирает входящий http.Request без сокета; httptest.NewRecorder возвращает ResponseRecorder — http.ResponseWriter, который вместо отправки в сеть записывает статус, заголовки и тело в свои поля. Сигнатура ServeHTTP — ровно интерфейс http.Handler: func(w http.ResponseWriter, r http.Request), поэтому Echo встаёт в httptest.NewServer и в любой тест без адаптеров. Полезная веха для доверия: echo проверяет сам себя тем же способом — в echo_test.go и json_test.go фреймворка стоят строки req := httptest.NewRequest(...) и e.ServeHTTP(rec, req), а ассерты сделаны через testify, который и в вашем go.mod появится рядом с тестами.

Запрос для теста — это не просто структура, а набор значений, на которые ваши хендлеры рассчитывают в проде. httptest.NewRequest(method, target, body) документирует их честно, и каждое стоит знать по имени. Target — «request-target» из RFC 7230: путь или абсолютный URL; если хоста в нём нет, Request.Host становится example.com. Протокол всегда HTTP/1.1 — даже если внутри NewRequest пишет в парсер строку с HTTP/1.0, чтобы не требовать Host, а потом чинит версию на внешнюю. Пустой method означает GET. Тело с типами bytes.Buffer, bytes.Reader и *strings.Reader получает корректный ContentLength; прочие reader-ы — -1 и заворачивание в io.NopCloser. Наконец, RemoteAddr — «192.0.2.1:1234»: адрес из диапазона TEST-NET, зарезервированного RFC 5737 специально для документации и примеров, чтобы тестовый запрос невозможно было спутать с настоящим.

Две детали, которые экономят часы. Первая: NewRequest паникует на невалидных аргументах — «NewRequest panics on error for ease of use in testing, where a panic is acceptable»; в тесте паника — это и есть провал, ошибки не нужны. Вторая: для target с https:// запрос получает фиктивное, но наполненное TLS.ConnectionState — Version TLS12 и HandshakeComplete true, — поэтому ветки вида c.Request().TLS != nil в тесте проверяются без сертификатов. Конструктора запросов у самого Echo нет — ни e.NewHTTPRequest, ни echo.NewRequest в исходниках v4.15.0 не существует: входящий запрос собирает стандартная библиотека, а Echo оборачивает его в контекст. Это осознанная граница: Echo — обработчик запросов, и его API начинается с уже готового *http.Request.

ServeHTTP — метод, через который Echo встаёт в http.Server, и в тесте он делает всё то же самое, минуя сокет. Исходник echo.go v4.15.0 стоит процитировать целиком: «c := e.pool.Get().(*context); c.Reset(r, w)» — контекст берётся из пула и привязывается к вашей паре запрос-рекордер; дальше «e.findRouter(r.Host).Find(r.Method, GetPath(r), c)» — роутер ищет узел и раскладывает параметры; «h = applyMiddleware(h, e.middleware...)» — найденный хендлер оборачивается всеми глобальными слоями; «if err := h(c); err != nil { e.HTTPErrorHandler(err, c) }» — исходящая ошибка попадает в ваш ErrorHandler с конвертом; наконец «e.pool.Put(c)» — контекст возвращается в пул. Здесь же живут premiddleware, если вы их завели. Для теста важно следствие: всё, что вы проверяли curl-ом в прошлых уроках — статусы, заголовки, конверты, Allow из 405, — воспроизводится вызовом e.ServeHTTP(rec, req) без порта и без запуска main.

Пул контекстов — та деталь, из-за которой тесты Echo дешёвые: pool.New создаёт контекст через e.NewContext(nil, nil), Reset перецепляет его на новую пару запрос-ответ, и на тысячу тестов приходятся тысячи переиспользований. Путь берётся функцией GetPath — RawPath, а если пусто, Path из URL — «GetPath returns RawPath, if it's empty returns Path from URL», так что проценты в адресе тестируются как на проде. Единственное, чего нет в этой цепочке, — сети: RemoteAddr возьмётся из TEST-NET адреса NewRequest, TLS будет nil или фиктивным, а соединение не потемнеет ни на байт — ровно то, что нужно детерминированному тесту.

Тест на каждый кейс — это десять функций с копипастой и усталость от добавления одиннадцатого. Идиома table-driven test, которой пропитана стандартная библиотека и собственные тесты Echo — router_test.go держит сотни кейсов в срезах структур, — собирает кейсы в таблицу и гонит её одним циклом. Форма: срез анонимных структур {name, входы, ожидания}, цикл t.Run(tc.name, func(t *testing.T){...}) на каждый кейс. t.Run даёт каждому кейсу имя в отчёте — TestStack/нет_заголовка — и точечный запуск: go test -run TestStack/нет_заголовка гоняет один кейс из матрицы, что экономит минуты на большом приложении.

Три правила дисциплины. Первое: свежая пара req/rec на кейс внутри цикла — рекордер копит тело и статус, и второй кейс на первом рекордере увидит чужой ответ; это не оптимизация, а корректность. Второе: сообщения ассертов содержат кейс — assert.Equal(t, tc.want, rec.Code, tc.name): упавший тест должен называть сценарий, а не строку в таблице. Третье: t.Parallel() внутри subtests включайте, только когда кейсы не делят состояние — и таблица, и приложение под тестом должны переживать параллельность; у Echo сам e потокобезопасен после конфигурации, но ваш мок-хранилище и replay-карта из семнадцатого урока — нет, у них свои мьютексы.

Тест всего стека упирается в вопрос: чем заменить хранилище? Глобальная переменная var store = map[int]task{...}, которой канон жил до сих пор, в тестах — мина: она переживает кейсы, связывает их порядком и не даёт повторить сценарий «хранилище упало». Решение старое, как Go: сузить зависимость до интерфейса и инъектировать реализацию. type TaskStore interface { List(offset, limit int) ([]task, int); Create(title string) task; Delete(id int) error } — и хендлеры получают его не из пакета, а из фабрики: makeTasksHandler(s TaskStore) echo.HandlerFunc. main собирает сервер с настоящим хранилищем, тесты — с fake-хранилищем на карте под мьютексом. Это юнит-принцип «мок-зависимости вместо глобальных задач», сформулированный ещё в анонсе девятнадцатого урока.

Fake — не заглушка, а вторая реализация контракта. У неё есть смысл проверять сценарии, которых настоящий store в тесте не даст: Delete возвращает ошибку — хендлер обязан отдать 404, а не запаниковать; Create после полного лимита — 409 или 422 по вашему контракту. Удобный приём — фабрика хендлеров + фабрика приложения: newTestEcho(s TaskStore) собирает маршруты с хендлерами от этого store, и каждый тест получает своё приложение с собственным состоянием. Полная версия этого трюка — слои и инъекция зависимостей по-взрослому — тема двадцать первого урока; здесь достаточно интерфейса, чтобы тесты перестали знать о существовании настоящего хранилища.

Middleware тестируется той же парой e.NewContext/рекордер, но с двумя приёмами поверх. Первый — подмена next: слой — это func(next echo.HandlerFunc) echo.HandlerFunc, поэтому в тесте next — ваш собственный флажок: called := false; h := mw(func(c echo.Context) error { called = true; return c.String(http.StatusOK, "ok") }). Вызов h(c) говорит всё о слое: вызван ли next, что слой успел сделать до и после, какой ответ дойдёт до клиента при отказе слоя. Для гвардов это главный ассерт: требуемый токен — called == true, чужой — 401 и called остался false, потому что до next дело не дошло.

Второй приём — подсевание контекста. Гвард requireRole из пятнадцатого урока читает c.Get("user") — туда кладёт echo-jwt. Тестировать гварда вместе с echo-jwt значит тащить в юнит-тест всю аутентификацию; вместо этого тест подсевает c.Set("user", token) руками — token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{"role": "admin"}), — и гвард исполняется в изоляции. Контракт c.Set/c.Get из восьмого урока делает это легальным: слой не знает, кто положил значение, ему важен ключ. Сквозная логика слоя — Skipper из седьмого урока, порядок слоёв из шестого — проверяется отдельно: Skipper зовётся с контекстом, и таблица путей в тесте скажет, на каких маршрутах слой спит.

Честные границы — половина тестовой дисциплины. ResponseRecorder не симулирует транспорт: нет таймаутов и обрывов соединения, нет реального chunked-кодирования — Writer просто пишет в буфер, — нет HTTP/2 и сжатия на уровне сервера. Ветку «клиент умер посреди стрима» этим инструментом не построишь: для неё нужен httptest.NewServer с настоящим клиентом, который закрывает соединение, — и тесты Echo так и делают там, где сырому Recorder тесно. Вторая граница — Result(): «Result must only be called after the handler has finished running» — он отдаёт снепшот на момент вызова; читать его из горутины параллельно хендлеру — гонка, которую vet подсветит, а тест всё равно иногда пройдёт.

Третья граница — числа. Код статуса Recorder проверяет только на три цифры: «checkWriteHeaderCode: if code < 100 || code > 999 { panic(fmt.Sprintf("invalid WriteHeader code %v", code)) }» — «For now we only enforce that it's three digits». Content-Type при первом Write подбирается http.DetectContentType, если вы его не выставили — снэппинг живого сервера, удобно и для тестов. И HeaderMap помечен как Deprecated: «To access the headers returned by a handler, use the Response.Header map as returned by the Result method» — читайте заголовки после хендлера через rec.Result().Header, а не по живой карте, которую хендлер ещё правит. Знание границ превращает «тест не проходит» в «тест инструменту не по зубам» — и это два разных исправления.

У канона появился страховочный трос. Юнит-уровень: e.NewContext с парой из httptest — хендлеры и гварды проверяются без роутера, подсевание c.Set заменяет echo-jwt, а подмена next показывает, дошло ли исполнение. Стек-уровень: e.ServeHTTP гоняет запрос через пул, роутер, applyMiddleware и ErrorHandler — table-driven матрица держит контракт JWT-отказов 400/401/403, а конверт ошибок из десятого урока теперь закреплён тестом. Мок-зависимости: TaskStore как интерфейс и фабрика хендлеров разорвали связь с глобальной картой — fresh fake на тест, сценарные отказы ручкой err. Границы честные: Flushed для SSE проверяется рекордером, Hijack для ws — только настоящим сервером. Каждый факт сверен с исходниками: echo.go и router_test.go v4.15.0, recorder.go и httptest.go стандартной библиотеки.

Про песочницу честно, как во всём курсе: у курса Echo её нет — код исполняется локально, поэтому runner-ов здесь не будет; соберите main_test.go из канона и запустите go test ./... -v: юниты летят за миллисекунды, матрица auth — за десятки, а единственный тест, потребовавший сети, — ws — попросит себе httptest.NewServer.

Следующий, двадцать первый урок курса echo — Структура проекта: слои, инъекция зависимостей, шаблон проекта. Фабрика makeTasksHandler уже намекнула: store и хендлеры разъедутся по слоям, newTestEcho обрастёт конструктором, а тесты лягут рядом с кодом. Навигация по курсу — на странице курса Echo; цепочка слоёв и c.Set/c.Get, на которых стоят подсевание и подмена next, — в уроке про middleware; конверт {error, code}, закреплённый стек-тестом, — в уроке про HTTPError; матрица echojwt 400/401/403 — в уроке про JWT; Flushed и границы SSE — в уроке про Server-Sent Events.