Supertest e integración HTTP

Supertest envía solicitudes HTTP a aplicaciones Express y Fastify en el mismo proceso sin vincular un puerto, lo que hace que las pruebas de integración sean rápidas y seguras para la ejecución en paralelo.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

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

npm install -D supertest @types/supertest

Cuándo usarlo:

• Probar rutas, orden de middleware y códigos de estado.
• Validar cuerpos de solicitud/respuesta JSON y encabezados de autenticación.
• Evitar colisiones de puertos inestables en CI paralelo.

Ejemplo de trabajo

// 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 returns ok", async () => {
    const res = await request(createApp()).get("/health");
    assert.equal(res.status, 200);
    assert.deepEqual(res.body, { status: "ok" });
  });
 
  it("POST /items validates body", 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");
  });
});

Lo que esto demuestra:

• La fábrica createApp() evita los efectos secundarios de listen().
• Supertest funciona con node:test (no se requiere Jest).
• Afirma sobre res.body JSON analizado, no cadenas sin procesar.

Análisis detallado

Cómo funciona

• Supertest envuelve el servidor HTTP de Node e inyecta solicitudes a través de un socket interno.
• La ausencia de un puerto de red significa que las pruebas se ejecutan en paralelo sin EADDRINUSE.
• La pila de middleware se ejecuta de forma idéntica a la producción hasta que se simulan las dependencias.
• Fastify: usa app.inject() de forma nativa o Supertest después de app.ready().

Alternativa de inyección de Fastify

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

• Los tipos de Express 5 se envían con el paquete en pilas de Node 24.
• Escribe el retorno de createApp() como express.Application o FastifyInstance para obtener ayuda del editor.

Errores comunes

• Llamar a listen() en el módulo de la aplicación - El puerto se vincula al importar; las pruebas luchan contra el servidor de producción. Solución: exporta la fábrica; escucha solo en server.ts.
• Singleton de DB mutable compartido - Las pruebas paralelas corrompen los datos. Solución: reversión de transacciones por prueba o repositorio en memoria en pruebas HTTP unitarias.
• Falta de await en la solicitud - Supertest devuelve Test; debe await la promesa en pruebas asíncronas. Solución: siempre await request(...).get().
• Fuga de estado de cookies/sesiones - El agente persiste las cookies entre llamadas sin intención. Solución: request.agent(app) solo al probar sesiones; request(app) nuevo de lo contrario.
• Probar solo el camino feliz - Errores 500 sin manejar. Solución: pruebas basadas en tablas para casos 400/401/404/409.

Alternativas

Preguntas frecuentes

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

Relacionado

• Conceptos básicos de prueba - ubicación de la pirámide para pruebas HTTP
• Testcontainers - DB real detrás de la capa HTTP
• Vitest - ejecutor con ergonomía de simulacros

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.