supertest
Тема дорожной карты · Node.js
supertest — это npm-пакет для интеграционного тестирования HTTP-серверов в Node.js, оборачивающий superagent для предоставления fluent API для выполнения HTTP-запросов к Express, Fastify, Koa или любому экземпляру http.Server без привязки к реальному сетевому порту. С помощью supertest разработчики Node.js пишут интеграционные тесты, запускающие сервер внутри процесса, отправляющие запросы GET, POST, PUT и DELETE с заголовками и телом, и проверяющие коды статуса, заголовки ответа и JSON-полезные нагрузки — всё в единой читаемой цепочке вида request(app).post('/users').send({ name: 'Alice' }).expect(201). supertest естественно интегрируется с тест-раннерами jest и vitest в TypeScript-проектах Node.js, а использование его совместно с реальной или in-memory базой данных обеспечивает сквозное покрытие логики маршрутизации, middleware, валидации и сохранения данных без сетевых накладных расходов. Для TypeScript-проектов supertest требует @types/supertest для деклараций типов, а режим agent в supertest поддерживает сессионные куки в рамках нескольких запросов, обеспечивая тестирование потоков аутентификации в серверных приложениях Node.js. supertest считается лучшей практикой тестирования HTTP API Node.js, поскольку проверяет полный жизненный цикл запроса, включая middleware, в отличие от юнит-тестов, напрямую вызывающих функции-обработчики.
Как это работает
supertest имеет несколько test-runner: встроенный node:test (Node 20+, без установки), Vitest (быстрый, Vite-native, Jest-совместимый), Jest (зрелый, большая экосистема), Mocha (классический, гибкий). Ассерты: node:assert, chai, expect. Моки: встроенный mock в node:test, sinon, vitest mock. Integration-тесты обычно поднимают приложение + test DB; HTTP-ассерты через supertest. Coverage — через c8 или nyc.
Когда применять
Vitest — для новых проектов: быстрый, ESM-native, watch-mode перезагружает только изменившееся. node:test — для zero-dependency ситуаций (CI-раннеры, внутренности npm-пакетов). Jest — только в legacy. Тесты в CI на каждый PR. Реальная test DB для integration-тестов (testcontainers поднимает на запуск); мокайте только реально внешнее (third-party API, payment-шлюзы).
Типичные ошибки
Ловушки supertest: тесты, делящие state (строка БД из теста A роняет тест B); over-mocking (тестируете моки, не код); process.exit() в тестах (убивает runner); нет timeout (висящий promise вешает suite); snapshot-тесты на нестабильном выводе (каждое изменение — diff). Тестовый suite — это production-код; рефакторьте его, именуйте хорошо.