Tema 14 · Testing con Supertest

14. Testing Automatizado de Endpoints con Supertest y Vitest/Jest

Escribe tests de integración completos simulando peticiones HTTP reales contra la instancia de Express sin necesidad de abrir sockets de red en puertos efímeros.

Testing de Integración sin Fricción con Supertest

Supertest permite testear peticiones HTTP sobre la instancia exportada de Express de forma casi instantánea. Pasa la solicitud directamente al controlador a través de los middlewares (autenticación, validación Zod, rate limit) y permite aserciones fluidas sobre códigos de estado, cabeceras y estructura de JSON.

1. Qué Testear en un Endpoint REST

  • Casos de Éxito (Happy Path): Código de estado esperado (200 OK, 201 Created), cabecera Content-Type: application/json y estructura del body.
  • Validación de Entrada (400 Bad Request): Envío de payloads vacíos, tipos erróneos o campos faltantes, verificando que el validador Zod rechace con mensajes descriptivos.
  • Seguridad y Autenticación (401 Unauthorized / 403 Forbidden): Peticiones sin token Bearer o con tokens expirados/adulterados.

⚡ Suite de Tests de Integración con Vitest y Supertest

Testing completo de endpoints POST y GET con aserciones semánticas.

auth.test.js
Solo lectura
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import request from 'supertest';
import { createApp } from '../src/app.js';
import { pool } from '../src/db.js';

describe('Endpoints de Autenticación y Usuarios (/api/v1)', () => {
  let app;

  beforeAll(async () => {
    // Inicializar la app de Express sin invocar app.listen()
    app = createApp();
  });

  afterAll(async () => {
    // Cerrar conexiones para permitir que Vitest finalice limpiamente
    await pool.end();
  });

  describe('POST /api/v1/auth/registro', () => {
    it('debe responder con 400 cuando el email no tiene formato válido', async () => {
      const response = await request(app)
        .post('/api/v1/auth/registro')
        .send({
          nombre: 'Carlos',
          email: 'correo-invalido-sin-arroba',
          password: 'PasswordSeguro123!',
        })
        .expect('Content-Type', /json/)
        .expect(400);

      expect(response.body.success).toBe(false);
      expect(response.body.error).toContain('validación');
    });

    it('debe registrar un nuevo usuario con éxito y devolver HTTP 201', async () => {
      const uniqueEmail = `test_${Date.now()}@kilopolis.com`;

      const response = await request(app)
        .post('/api/v1/auth/registro')
        .send({
          nombre: 'Desarrollador Kilopolis',
          email: uniqueEmail,
          password: 'PasswordSeguro123!',
        })
        .expect(201);

      expect(response.body.success).toBe(true);
      expect(response.body.data).toHaveProperty('id');
      expect(response.body.data.email).toBe(uniqueEmail);
      // Regla de seguridad: el password_hash nunca debe ser devuelto en la respuesta
      expect(response.body.data).not.toHaveProperty('password_hash');
    });
  });

  describe('GET /api/v1/perfil (Ruta Protegida)', () => {
    it('debe denegar el acceso con 401 si no se envía la cabecera Authorization', async () => {
      const response = await request(app)
        .get('/api/v1/perfil')
        .expect(401);

      expect(response.body.success).toBe(false);
    });
  });
});
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Cuál es una ventaja fundamental de pasar la instancia createApp() a request(app) en Supertest?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar Express.js: Framework Backend & APIs Empresariales y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.