Интеграционное тестирование HTTP API

Что интеграционный тест покрывает, а юнит — нет

Спроси себя: когда последний раз баг пробился в прод, несмотря на зелёные юнит-тесты? Скорее всего, он жил на шве — порядок middleware, неверный статус-код, auth-гард на не том пути. Это именно тот зазор, который закрывают интеграционные тесты.

Юнит-тест фиксирует одну функцию с заглушенными коллабораторами: быстрый, точечный и слепой к проводке. Интеграционный тест прогоняет весь путь запроса — роутер → цепочка middleware → хендлер → (обычно) реальная база — через настоящую HTTP-поверхность. Именно там живёт класс багов, до которого юнит-тесты структурно не дотягиваются: порядок middleware, забытый await в роуте, сериализатор, теряющий поле, статус-код 200 там, где должен быть 201, рассинхрон content negotiation, auth-гард, повешенный на не тот путь. Хендлер может быть верен сам по себе, а сборка всё равно сломана.

В пирамиде тестов интеграционные стоят выше юнитов и ниже end-to-end: их больше, чем E2E (которые гоняют реальный браузер/сеть и потому медленны и флейки), и меньше, чем юнитов. Отдача на тест высока — один интеграционный тест покрывает швы на много юнитов, — но каждый дороже в прогоне, так что тысячами их не пишут. Классический провал — «рожок мороженого»: почти все тесты в медленном конце, полая середина, и контрактные баги утекают в прод.

supertest: настоящие HTTP-вызовы без управления портом

supertest оборачивает любой Node-обработчик http — app Express или Fastify, или голый (req, res) => … — и на каждый вызов поднимает его на эфемерном порту (или диспетчеризует in-process), шлёт настоящий HTTP-запрос и сносит слушатель. Ты никогда не выбираешь порт, не рискуешь EADDRINUSE от захардкоженного 3000 и проверяешь реальную строку статуса, заголовки и распарсенное тело.

import { test } from "node:test";
import assert from "node:assert/strict";
import request from "supertest";
import { app } from "../src/app.js"; // НЕ вызывай здесь app.listen()

test("POST /users создаёт пользователя", async () => {
  const res = await request(app)
    .post("/users")
    .send({ email: "a@b.com" })   // ставит JSON-тело + content-type
    .expect("Content-Type", /json/)
    .expect(201);

  assert.equal(res.body.email, "a@b.com");
  assert.match(res.headers.location, /^\/users\/\d+$/);
});

Передавай сам app, а не запущенный сервер — supertest управляет слушателем, чтобы жизненным циклом владел тест. Поскольку вызов идёт по настоящему HTTP, он ловит баг проводки из хука: порядок middleware, парсинг тела и статус-код все в игре, а не заглушены.

Реальная база: четыре стратегии, четыре компромисса

База — это то, ради чего интеграционные тесты и нужны, и то, на чём они ломаются. Четыре частых подхода:

Rollback оборачивает каждый тест в транзакцию и обрывает её в конце — ничего не коммитится, так что следующий тест видит чистую базу при нулевой цене сброса. Это самый быстрый вариант с сильной изоляцией, но он не может тестировать код, который сам коммитит или полагается на видимость транзакции (нельзя откатить то, что твой код уже закоммитил, а трюки с вложенными транзакциями меняют семантику). Truncate/сброс проще и позволяет тестировать логику коммита ценой явной записи-очистки между тестами. Testcontainers поднимает реальный Postgres или Redis в одноразовом Docker-контейнере на набор: наивысшая достоверность, потому что это тот же движок, версия и SQL-диалект, что в проде, — ценой секунд старта контейнера. In-memory SQLite быстра и заманчива, но это другая база: она не проверит твои типы Postgres, в ней нет JSONB, RETURNING, частичных индексов и многих ограничений, так что зелёный набор на SQLite может прятать SQL, который взрывается на реальном Postgres в проде. Предпочитай реальный движок (Testcontainers) ради достоверности; берись за rollback, когда правит скорость набора.

Изоляция и зависание на открытых хендлах

Интеграционному набору можно доверять, только если каждый тест независим: ни оставшихся строк из прошлого теста, ни зависимости от порядка, ни общего изменяемого состояния. Сей детерминированные фикстуры внутри каждого теста (или свежую транзакцию на тест), направляй набор на выделенную тестовую базу или схему — никогда на общую dev-БД — и давай параллельным воркерам отдельные схемы или базы, чтобы два воркера не дрались за одни строки. Флейк из хука — каноническое нарушение: тесты против общей БД становятся зависимыми от порядка, взаимно разрушительными и проходят-или-падают по везению.

Второй классический отказ — процесс, который не выходит. Если ты открыл слушатель сервера или пул соединений к БД и не закрыл их, тест-раннер Node заканчивает проверки, но в event loop ещё есть живые хендлы, так что процесс зависает (или ругается на открытые хендлы / утёкшие таймеры). Всегда закрывай всё в teardown:

import { test, after } from "node:test";
import { pool } from "../src/db.js";

// node:test запускает хуки `after`, когда тесты файла завершились
after(async () => {
  await pool.end();   // закрыть пул соединений к БД
  // если поднимал слушатель — server.close() тоже
});

С supertest ты обычно вообще не поднимаешь слушатель (он управляет эфемерными), так что забытый хендл — это пул. Зависший CI-джоб, отваливающийся по таймауту через десять минут, почти всегда — незакрытый пул или сокет, а не медленный тест.