Las pruebas de las dos lecciones anteriores están verdes: el dominio calcula bien, la matriz de permisos es correcta celda por celda, el conversor de divisas degrada con elegancia. Y aun así, la API de Escena Viva podría estar completamente rota.

Considera este escenario, que ocurre de verdad. Alguien reordena los middlewares en crearAplicacion y coloca la ruta de pedidos antes que express.json(). Resultado: req.body llega undefined, el esquema zod rechaza todo y cada compra devuelve 400. ¿Cuántas pruebas unitarias lo detectan? Ninguna. El controlador funciona perfectamente cuando le pasas un req fabricado a mano, el esquema valida bien lo que se le da, el repositorio guarda correctamente. Todas las piezas están bien; el cableado está mal.

Eso es lo que prueban las pruebas de integración: que las piezas encajan cuando se ejecutan juntas de verdad.

1. Qué integra una prueba de integración
2. supertest y el diseño del módulo 6
3. La primera prueba de extremo a extremo
4. La base de datos en las pruebas
5. Aislamiento entre pruebas
6. Autenticar en las pruebas
7. Probar los caminos que importan
8. Probar la concurrencia contra la sobreventa
9. Contrato del formato de error y servicios externos

Una prueba de integración ejecuta varias capas reales juntas. Una petición a POST /api/pedidos recorre esto:

Cada flecha es un punto de fallo invisible para una prueba unitaria: middleware mal ordenado o no montado; una ruta con el verbo o el prefijo incorrectos; manejadorDeErrores colocado antes que las rutas y por tanto nunca alcanzado; un esquema zod que valida un campo que el controlador espera con otro nombre; el repositorio devolviendo un documento de Mongoose donde se espera un objeto del dominio; la transacción del módulo 7 que en la práctica no aísla lo que creemos; y el estado HTTP real de cada error de la jerarquía.

Qué hace supertest, exactamente: toma tu aplicación de Express, la arranca en un puerto efímero que le asigna el sistema operativo, hace una petición HTTP real contra ese puerto y cierra el servidor al terminar. Es una petición de verdad, no una simulación: pasa por todos los middlewares, el enrutador, el parseo del cuerpo y el manejador de errores. Y como el puerto es efímero, nunca chocarás con un EADDRINUSE aunque tengas el servidor de desarrollo en el 3000.

Aquí se cobra una decisión del módulo 6 que entonces pudo parecer un capricho: src/app.js exporta una factoría que nunca llama a listen, y es src/servidor.js quien conecta la base de datos, escucha y gestiona el apagado ordenado. Gracias a esa separación, la prueba es una línea:

Si app.js llamara a listen al cargarse —el error más común en proyectos de Express—, cada fichero de pruebas abriría un servidor en el 3000, el segundo fallaría y el proceso no terminaría nunca. Esa es la razón real de la factoría.

La última tiene un matiz: desactivar los límites está bien, pero entonces hay que probarlos en un fichero aparte con limitar: true, o nadie comprobará nunca que funcionan.

La tercera es de las más rentables que existen: comprueba que la serialización no filtra los campos internos de Mongoose. Es un fallo que aparece en cuanto alguien devuelve el documento crudo en lugar del objeto del dominio, y que nadie mira hasta que un cliente pregunta qué es __v.

El repertorio se encadena: .post(ruta), .set(cabecera, valor), .send(cuerpoJSON), .query({ divisa: 'GBP' }), .expect(estado), .expect('Content-Type', /json/) y .expect((res) => ...) para una aserción a medida sobre la respuesta.

Consejo práctico: usa .expect() para el estado y las cabeceras, y Chai para el cuerpo, porque los mensajes de fallo de Chai sobre objetos son mucho más informativos. Y si escribes .expect(200) y el servidor devuelve 500, supertest imprime los estados pero no el cuerpo del error: mientras depuras, guarda la respuesta e imprime respuesta.body.

Esta es la decisión de diseño más importante de la lección.

Nuestra elección: una base real dedicada, escena_viva_test. La prueba estrella de esta lección es la de concurrencia contra la sobreventa, que depende del comportamiento transaccional real del motor: con SQLite o con un repositorio falso pasaría siempre sin demostrar nada. Además ya tenemos la semilla idempotente del módulo 7, src/config/index.js es el único punto que lee process.env —cambiar de base es cambiar una variable— y en CI se levanta un servicio con dos líneas.

Creamos .env.test con NODE_ENV=test, MONGODB_URI=mongodb://localhost:27017/escena_viva_test, DATABASE_URL=postgres://escena:escena@localhost:5432/escena_viva_test, un JWT_SECRETO de pruebas, BCRYPT_COSTE=4, NIVEL_REGISTRO=silent y TZ=UTC. Y lo cargamos antes que nada desde el fichero de arranque de Mocha:

El orden importa muchísimo. src/config/index.js lee process.env al cargarse y congela el resultado; si dotenv corre después del primer require de un módulo que importe la configuración, tu prueba se conectará alegremente a la base de desarrollo y la borrará. Cargarlo desde el require de .mocharc.json, antes que cualquier otra cosa, es la garantía. Y como salvaguarda barata, una función comprobarBaseDePruebas() que lanza si configuracion.mongodbUri no incluye _test, invocada antes de cualquier borrado.

Las pruebas no pueden depender del orden en que se ejecutan. Si la prueba B solo pasa después de la A, tienes una bomba de relojería: el día que alguien añada .only, ejecute un solo fichero o active el paralelismo, B fallará sin motivo aparente.

Su uso en cada fichero es beforeEach(sembrarDatosDePrueba) y afterEach(limpiar). Por qué beforeEach y no before: porque la primera prueba que compre entradas modificará el aforo y la segunda esperaría un número distinto. Sembrar en cada prueba cuesta unos milisegundos y compra determinismo.

Compartir estado entre pruebas es la fuente número uno de pruebas intermitentes, y aparece en tres formas: un objeto de módulo mutado por una prueba y leído por otra, datos en la base que sobreviven a la prueba que los creó, y una caché en memoria (como la de cambio-divisas.js) que no se vacía.

Aquí está la promesa del módulo 8: casi todas las rutas interesantes exigen un usuario autenticado. ¿Cómo consigue la prueba un token válido?

La mala idea es hacer login desde la prueba con credenciales escritas en el código: mete credenciales en el repositorio (un hábito que acaba con una contraseña real en un commit), es lento porque cada login ejecuta bcrypt a propósito, acopla toda la batería al endpoint de login —si se rompe fallan cincuenta pruebas en vez de una— y es frágil ante cualquier cambio de la política de contraseñas.

La buena idea es una ayuda que crea el usuario que la prueba necesita y firma un token con el mismo servicio que usa la aplicación:

Se usa desplegando el array en .set(...): const lucia = await comoAsistente() y después request(app).post('/api/pedidos').set(...lucia.cabecera), o comoOrganizador('org-almendra') para editar un evento del Teatro Almendra. Verás decenas de ejemplos en el resto de la lección.

Por qué esto es correcto y no una trampa: usamos el mismo firmarAcceso que usa producción, así que el token pasa exactamente por la misma verificación que cualquier token real —firma HS256 con el mismo secreto, caducidad, formato de la carga—. No nos saltamos la autenticación; nos saltamos el login, que es una operación distinta y que se prueba aparte, una sola vez, en test/integracion/autenticacion.test.js: credenciales válidas, 401 con la misma latencia si el correo no existe (el señuelo de bcrypt), 401 con contraseña incorrecta y no revelar cuál de los dos falló.

La segunda prueba ata el mundo HTTP con el mundo de los datos: comprueba que la compra tuvo efecto real y persistente, no solo que devolvió 201.

Cada estado de error de la jerarquía del módulo 6 merece su prueba:

Faltan tres hermanas evidentes, del mismo molde: el 400 con un cuerpo que no cumple el esquema ({ cantidad: 'dos' }, sin sesionId, cuyo error.detalles debe ser un array con los fallos de zod), el 401 con un token manipulado (Bearer no.es.un.token) y el 403 de un asistente que intenta editar un evento.

De todas las pruebas del módulo, esta es la que más vale por línea escrita. Es el fallo de seguridad más común de las APIs REST: un identificador en la URL que el servidor sirve sin comprobar de quién es.

El 404 en vez de 403 es deliberado y lo decidimos en el módulo 8: responder 403 confirmaría a Marc que ese pedido existe, información que no le corresponde. La prueba fija esa decisión de seguridad para que nadie la deshaga creyendo que mejora los mensajes de error. Su complemento es la prueba de que un administrador sí puede ver el pedido de cualquier asistente.

Esta prueba valida todo el trabajo transaccional del módulo 7, y no existe forma de escribirla que no sea de integración.

La aserción decisiva es la última: vendidas nunca supera aforo. Si el módulo 7 hubiera implementado la compra con un leer → comprobar → escribir sin transacción ni actualización condicional, esta prueba pondría en evidencia la condición de carrera de inmediato: las diez compras leerían "5 libres", las diez pasarían la comprobación y venderíamos 20 entradas para 5 asientos.

Dos advertencias honestas: la prueba es no determinista en su detalle —el número exacto de éxitos puede variar si la lógica permite compras parciales, así que afirma la invariante y no un reparto concreto— y es lenta, unos cientos de milisegundos con base real. Merece la pena: es la prueba que impide vender una butaca dos veces.

El formato { error: { codigo, mensaje, estado, detalles } } es un contrato con quien consuma la API, y vale la pena fijarlo con una tabla de casos:

Merece añadir una prueba más, que comprueba que la respuesta de error no filtra la pila de llamadas: expect(body.error).to.not.have.property('stack') y expect(JSON.stringify(body)).to.not.include('node_modules'). Filtrar una traza al cliente revela rutas del servidor, versiones de librerías y a veces fragmentos de consultas, y es un fallo silencioso que aparece en cuanto alguien "mejora" el manejador de errores para depurar y olvida quitarlo.

En integración probamos nuestro sistema completo, pero no los servicios de terceros: llamar al proveedor real de tasas en cada ejecución produce pruebas lentas, intermitentes y dependientes de una cuota. La técnica es simular en el borde: mantener toda la integración real y sustituir únicamente la llamada saliente con Sinon.

Esta prueba tiene un valor enorme: garantiza que una caída de un proveedor externo no tumba el catálogo, un requisito de negocio real que solo una prueba de integración con el borde simulado puede demostrar.

Nota sobre extremo a extremo con navegador. Por encima está el nivel real: un navegador automatizado que abre la web, busca el Festival de Jazz, elige butacas, paga y comprueba que la entrada aparece. Playwright es hoy la referencia en Node, con Cypress como alternativa. Está fuera del alcance de este curso, que es de servidor, y hay una razón de fondo además del temario: son las pruebas más caras y frágiles de la pirámide. La recomendación profesional es tener muy pocas, solo sobre los flujos que hunden el negocio, y resolver el resto en los niveles de abajo, que es lo que hemos hecho.

• Apuntar a la base de desarrollo. Se descubre cuando desaparecen los datos. Carga .env.test desde el require de Mocha y comprueba _test antes de cualquier borrado.
• Olvidar await en supertest. request(app).get('/api/eventos').expect(200) sin await devuelve una promesa: la prueba pasa siempre. Es la trampa de 09-02 disfrazada.
• Dejar los límites de peticiones activos. La prueba de concurrencia recibe 429 en lugar de 409 y culpas a la transacción.
• Sembrar en before en vez de beforeEach. Cada compra altera el aforo y la segunda prueba espera un número que ya no es el suyo. Y no hagas login en cada prueba: bcrypt es lento a propósito, para eso está la ayuda de autenticación.
• No cerrar la conexión al terminar. Con "exit": false el proceso se queda colgado: ese es el afterAll con desconectar(). Y no dependas del orden de un array: Mongo no lo garantiza sin sort, así que busca por id con datos.find(...).
• Consejo: cuando una prueba de integración falle, imprime respuesta.body antes que nada; el cuerpo del error suele decir exactamente qué pasó. Y ejecuta la batería dos veces seguidas sin limpiar a mano: si la segunda falla, tu limpieza es incompleta.

Crea test/integracion/limites.test.js con una aplicación construida con limitar: true. Escribe una prueba que repita POST /api/autenticacion/login hasta superar limiteLogin y compruebe que la última devuelve 429 con su código y la cabecera Retry-After. Piensa cómo evitar que este fichero contamine a los demás.

Escribe las pruebas del refresco rotatorio del módulo 8: que POST /api/autenticacion/refrescar con una cookie válida devuelve 200 y una cookie nueva distinta; que reutilizar la cookie antigua después de rotarla devuelve 401 y revoca la familia entera; y que tras la revocación ni siquiera la cookie nueva funciona.

Escribe las pruebas de GET /api/eventos/:id/informe, que solo puede consultar el organizador propietario de la sala o un administrador. Cubre 200 para el organizador propietario, 403 para el de otra sala, 403 para el asistente, 401 sin token, 200 para el administrador y 404 para un evento inexistente pedido por un administrador.

Ejercicio 1

La contaminación se evita usando una instancia propia de la aplicación (cada crearAplicacion crea sus propios contadores de express-rate-limit) y no reutilizándola en otros ficheros. Si el almacén de límites fuera externo —Redis, módulo 10—, habría que vaciarlo en afterEach.

Ejercicio 2

Es una de las pruebas más valiosas del proyecto: la detección de reutilización es lógica de seguridad sutil que nadie recuerda seis meses después y que un refactor bienintencionado puede desactivar sin que se note.

Ejercicio 3

Las otras cuatro son del mismo molde: 403 para el organizador de org-boveda, 403 para el asistente, 401 sin token y 200 para el administrador. Fíjate en el orden que revelan estas pruebas: primero autenticación (401), después autorización (403) y solo entonces existencia (404). Si el 404 se comprobara antes que el 403, un asistente podría averiguar qué identificadores de evento existen sondeando la API.

Hemos subido un nivel en la pirámide y hemos ganado lo que las pruebas unitarias no podían dar: la certeza de que las piezas encajan. Ahora sabemos que las rutas están montadas, que los middlewares corren en el orden correcto, que manejadorDeErrores traduce cada error de la jerarquía a su estado HTTP y a su formato de contrato, que el aforo se descuenta de verdad en la base de datos, que un asistente no puede ver el pedido de otro, y que diez compras simultáneas por cinco butacas venden cinco butacas.

Y hemos resuelto la promesa del módulo 8 con test/ayudas/autenticacion.js: una ayuda que crea el usuario con el rol necesario y firma un token válido con el mismo servicio que usa la aplicación, sin una sola contraseña escrita en el código y sin pagar el coste de bcrypt en cada prueba.

Nos queda una pregunta incómoda. Tenemos muchas pruebas, ¿pero cubren lo que importa? ¿Hay ramas del código que ningún it ha ejecutado jamás? ¿Cuánto tarda la batería y qué pasará cuando tarde el triple? ¿Cómo se asegura el equipo de que nadie sube código con las pruebas rojas?

En la lección siguiente, Cobertura y Automatización de las Pruebas, medimos qué estamos probando de verdad con c8, fijamos umbrales que solo pueden subir, organizamos los scripts de npm, aprendemos a cazar una prueba intermitente y dejamos el proyecto listo para que un servidor de integración continua ejecute todo esto sin intervención humana.