Supertest & HTTP Integration

Supertest envia requisições HTTP para aplicações Express e Fastify no mesmo processo, sem a necessidade de vincular uma porta, tornando os testes de integração rápidos e seguros para execução paralela.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import request from "supertest";
import { createApp } from "../src/app.js";
 
const res = await request(createApp()).get("/health");

npm install -D supertest @types/supertest

Quando usar:

• Testar rotas, ordem de middleware e códigos de status.
• Validar corpos de requisição/resposta JSON e cabeçalhos de autenticação.
• Evitar colisões de porta instáveis em CI paralela.

Exemplo de Trabalho

// src/app.ts
import express from "express";
 
export function createApp() {
  const app = express();
  app.use(express.json());
 
  app.get("/health", (_req, res) => {
    res.json({ status: "ok" });
  });
 
  app.post("/items", (req, res) => {
    if (!req.body?.name) {
      return res.status(400).json({ error: "name required" });
    }
    res.status(201).json({ id: "item_1", name: req.body.name });
  });
 
  return app;
}

// test/app.http.test.ts
import assert from "node:assert/strict";
import { describe, it } from "node:test";
import request from "supertest";
 
import { createApp } from "../src/app.js";
 
describe("HTTP API", () => {
  it("GET /health retorna ok", async () => {
    const res = await request(createApp()).get("/health");
    assert.equal(res.status, 200);
    assert.deepEqual(res.body, { status: "ok" });
  });
 
  it("POST /items valida o corpo", async () => {
    const res = await request(createApp())
      .post("/items")
      .send({})
      .set("Content-Type", "application/json");
 
    assert.equal(res.status, 400);
    assert.equal(res.body.error, "name required");
  });
});

O que isto demonstra:

• A factory createApp() evita efeitos colaterais de listen().
• Supertest funciona com node:test (não requer Jest).
• Assert sobre res.body JSON parseado, não strings brutas.

Mergulho Profundo

Como Funciona

• Supertest envolve o servidor HTTP do Node e injeta requisições através de um socket interno.
• Nenhuma porta de rede significa que os testes rodam em paralelo sem EADDRINUSE.
• A pilha de middleware executa identicamente à produção até que você simule dependências.
• Fastify: use app.inject() nativamente ou Supertest após app.ready().

Alternativa Fastify inject

import Fastify from "fastify";
 
const app = Fastify();
app.get("/health", async () => ({ ok: true }));
await app.ready();
 
const res = await app.inject({ method: "GET", url: "/health" });
// res.statusCode, res.json()

Notas de TypeScript

• Os tipos do Express 5 vêm com o pacote em stacks Node 24.
• Digite o retorno de createApp() como express.Application ou FastifyInstance para ajuda do editor.

Armadilhas

• Chamar listen() no módulo do app - A porta é vinculada na importação; os testes competem com o servidor de produção. Correção: exportar uma factory; chamar listen() apenas em server.ts.
• Singleton de DB mutável compartilhado - Testes paralelos corrompem os dados. Correção: rollback de transação por teste ou repositório em memória em testes HTTP unitários.
• Falta de await na requisição - Supertest retorna um Test; é preciso usar await na promise em testes assíncronos. Correção: sempre usar await request(...).get().
• Vazamento de estado de cookie/sessão - O agente persiste cookies entre chamadas não intencionalmente. Correção: usar request.agent(app) apenas ao testar sessões; usar request(app) novo caso contrário.
• Testar apenas o caminho feliz - Erros 500 não tratados. Correção: testes orientados por tabela para casos 400/401/404/409.

Alternativas

FAQs

await request(app).get("/me").set("Authorization", "Bearer test-token");

Relacionados

• Noções Básicas de Teste - posicionamento na pirâmide para testes HTTP
• Testcontainers - DB real por trás da camada HTTP
• Vitest - runner com ergonomia de mock

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.