Supertest para JavaScript (Node.js): guía completa con ejemplos

¡Bienvenido a PythonLib! En este artículo analizaremos a fondo la librería Supertest, una de las herramientas más populares para pruebas HTTP en el ecosistema Node.js. Si desarrollas aplicaciones web con Express, Koa, Fastify o cualquier otro framework, Supertest se convertirá en tu aliado indispensable para escribir pruebas de integración sólidas y confiables.

1. ¿Qué es Supertest y para qué sirve?

Supertest es una librería de alto nivel para probar servidores HTTP en Node.js. Proporciona una API cómoda y expresiva para enviar solicitudes HTTP a tu aplicación y verificar las respuestas. Su principal ventaja es que permite probar el servidor sin necesidad de ejecutarlo en un puerto real: la librería utiliza mecanismos internos de Node.js para simular la conexión HTTP, lo que hace que las pruebas sean rápidas y estén aisladas.

¿Para qué sirve Supertest? En el desarrollo web moderno, la calidad del código es fundamental. Las pruebas de integración que verifican el funcionamiento de tus endpoints API ayudan a detectar regresiones, errores en el procesamiento de solicitudes y problemas de validación de datos. Supertest te permite escribir estas pruebas de forma concisa y legible, usando encadenamiento de métodos (chaining) y aserciones integradas para comprobar estados, cabeceras, cuerpo de la respuesta y mucho más. La librería se integra perfectamente con los ejecutores de pruebas más populares, como Jest, Mocha, Jasmine y AVA.

La librería fue creada por TJ Holowaychuk (autor de Express, Koa y muchos otros proyectos conocidos) y desde entonces es mantenida por la comunidad. Supertest está construida sobre la librería SuperAgent, un potente cliente HTTP para Node.js y el navegador. Esto significa que tienes acceso a todas las funcionalidades de SuperAgent, incluyendo soporte para diferentes tipos de datos, carga de archivos, manejo de cookies y mucho más.

2. Instalación

La instalación de Supertest se realiza a través del gestor de paquetes npm. Se recomienda instalar la librería como dependencia de desarrollo (devDependency), ya que no es necesaria en el entorno de producción.

npm install --save-dev supertest

Si usas yarn:

yarn add --dev supertest

Para trabajar con TypeScript, también puede ser necesario instalar los tipos:

npm install --save-dev @types/supertest

Ten en cuenta que Supertest requiere Node.js versión 14 o superior. Asegúrate también de tener instalado un ejecutor de pruebas (por ejemplo, Jest o Mocha).

3. Inicio rápido — ejemplo mínimo funcional

Vamos a crear una aplicación Express sencilla y escribir una prueba para ella usando Supertest. Este ejemplo mostrará el mecanismo básico de la librería.

Primero, creamos el archivo app.js con nuestra aplicación:

// app.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.status(200).json({ message: '¡Hola, Mundo!' });
});

app.get('/user', (req, res) => {
  res.status(200).json({ name: 'Juan Pérez', age: 30 });
});

module.exports = app;

Ahora creamos el archivo de prueba app.test.js:

// app.test.js
const request = require('supertest');
const app = require('./app');

describe('GET /', () => {
  it('debería devolver ¡Hola, Mundo!', async () => {
    const response = await request(app)
      .get('/')
      .expect(200);

    expect(response.body).toEqual({ message: '¡Hola, Mundo!' });
  });
});

describe('GET /user', () => {
  it('debería devolver los datos del usuario', async () => {
    const response = await request(app)
      .get('/user')
      .expect('Content-Type', /json/)
      .expect(200);

    expect(response.body.name).toBe('Juan Pérez');
    expect(response.body.age).toBe(30);
  });
});