La API de Escena Viva vende entradas, persiste pedidos con transacciones que impiden la sobreventa, autentica usuarios, rota tokens de refresco y autoriza operaciones según roles y propiedad del recurso. Hace muchísimas cosas. Y nadie ha comprobado nunca que funcione. Ni una sola vez.

npm test sigue fallando a propósito desde el módulo 5 con el mensaje Sin pruebas todavia — Modulo 9, y cada línea de seguridad que escribimos en el módulo anterior —el señuelo de bcrypt, la detección de reutilización del refresco, cada celda de la matriz de permisos— descansa hoy sobre la confianza de que la escribimos bien. Un if invertido en puedeGestionarEvento abriría el catálogo entero de eventos a cualquier organizador y nada avisaría.

En esta lección no escribiremos todavía la primera prueba ejecutable ni instalaremos nada: eso es la lección siguiente. Aquí construimos los cimientos conceptuales, que es lo que separa un proyecto con muchas pruebas de un proyecto con buenas pruebas.

1. Por qué se prueba: cambiar el código sin miedo
2. Qué es una prueba automatizada y la estructura AAA
3. Tipos de prueba y la pirámide
4. Qué probar y qué no: el criterio del riesgo
5. Qué hace buena a una prueba
6. Pruebas frágiles y falsos positivos
7. TDD explicado con honestidad
8. El panorama de herramientas para Node
9. El plan de pruebas de Escena Viva

Existe una idea muy extendida de que las pruebas sirven "por si acaso", como un seguro que quizá algún día se cobre. Es una descripción pobre y explica por qué tantos equipos las abandonan a las tres semanas. El valor real de una batería de pruebas es otro y es medible en el día a día: te devuelve la capacidad de modificar el código.

Hagamos la prueba del algodón con nuestro propio proyecto. Responde con honestidad:

• ¿Te atreverías hoy a reescribir comprarEntradas para agrupar varias sesiones en un solo pedido?
• ¿Te atreverías a refactorizar PERMISOS_POR_ROL para añadir el rol taquillero sin revisar manualmente las 30 combinaciones?
• ¿Te atreverías a cambiar el orden de dos middlewares en crearAplicacion para que autenticar corra antes que limiteCompra?
• ¿Te atreverías a subir la versión mayor de Mongoose?

Si la respuesta honesta es "no, o solo con mucho cuidado y probando a mano en el navegador", el código ya te está gobernando a ti. Esa parálisis tiene un coste que no aparece en ninguna factura: las funciones se van copiando en lugar de reutilizarse, los if se acumulan porque nadie borra ramas antiguas, y la deuda técnica crece porque tocar lo que ya funciona da miedo.

Una batería de pruebas convierte la pregunta "¿habré roto algo?" en un comando de diez segundos. Ese es el producto que compramos en este módulo. Los beneficios secundarios son reales pero secundarios:

Y hay algo que las pruebas no hacen, conviene decirlo desde el principio: no demuestran que el programa sea correcto. Demuestran que los casos que se te ocurrieron se comportan como esperabas. Es muchísimo, pero no es una garantía matemática.

Una prueba automatizada es simplemente un programa que ejecuta otro programa y comprueba el resultado, terminando con éxito o con error sin que nadie mire la pantalla. No hay magia: un fichero de pruebas es JavaScript normal.

La estructura universal se conoce como AAA (Arrange, Act, Assert), que en español llamaremos preparar, actuar y comprobar:

1. Preparar: construir el escenario. Datos, objetos, dobles de prueba, estado inicial.
2. Actuar: ejecutar exactamente una operación, la que se está probando.
3. Comprobar: verificar que el resultado observable es el esperado.

Veamos el primer ejemplo sobre una pieza real de nuestro dominio, Sesion.vender(). Todavía no es código ejecutable con Mocha —falta la instalación—, pero la anatomía ya es la definitiva:

Tres observaciones importantes sobre este boceto:

• La preparación es explícita y local. No leemos la sesión de la base de datos ni dependemos de la semilla. Si mañana alguien cambia el aforo de ses-001-1 en scripts/semilla.js, esta prueba sigue siendo válida. Una prueba que depende de datos lejanos es una prueba que fallará por motivos ajenos a lo que dice probar.
• Actuar es una sola línea. Si necesitas cinco llamadas para actuar, probablemente estés probando cinco cosas y el fallo no te dirá cuál.
• Comprobamos el comportamiento observable, libres, no el campo privado #vendidas. De hecho no podríamos: es privado. Eso es una ventaja, no un obstáculo.

Un cuarto paso implícito, la limpieza, aparecerá cuando haya recursos que liberar (conexiones, relojes falsos, ficheros). En el dominio puro no hace falta, y ese es justo su encanto.

No todas las pruebas cuestan lo mismo ni detectan lo mismo. Esta tabla es el mapa del módulo entero:

Las tres primeras forman la pirámide de pruebas: muchas unitarias en la base, bastantes de integración en el medio, muy pocas de extremo a extremo en la punta.

La forma no es un capricho estético: es economía. Una prueba unitaria de puedeGestionarEvento tarda menos de un milisegundo y, cuando falla, te señala una función concreta. Una prueba de extremo a extremo del mismo permiso tarda diez segundos, puede fallar porque el navegador tardó en cargar, y cuando falla te dice "el botón no aparecía", que puede significar cincuenta cosas distintas.

Cuando un equipo invierte la pirámide —muchísimas pruebas de extremo a extremo, algunas de integración, casi ninguna unitaria— obtiene el llamado cono de helado. Es un desastre reconocible por sus síntomas:

• La batería tarda 40 minutos y la gente deja de ejecutarla en local.
• Un cambio de una línea en una plantilla rompe treinta pruebas.
• Aparecen pruebas intermitentes (flaky): fallan una de cada cinco veces sin motivo aparente.
• Como fallan a menudo por ruido, el equipo empieza a reintentar hasta que pasen. En ese momento la batería ha dejado de aportar información y solo aporta espera.

La regla práctica: cada comportamiento se prueba al nivel más bajo que pueda demostrarlo. Sube de nivel solo cuando el nivel inferior no puede ver el problema.

Probarlo todo es imposible y perseguirlo produce baterías caras que envejecen mal. El criterio que usaremos es el riesgo, entendido como probabilidad de fallo multiplicada por el daño que causaría.

Sí se prueba:

• Lógica de negocio con reglas. Sesion.vender() valida cantidad, aforo y estado. Si se equivoca, vendemos entradas que no existen.
• La matriz de permisos. Un error aquí es una brecha de seguridad silenciosa.
• Cálculos. Totales en céntimos, límites de 6 entradas por pedido, ocupación, umbral de aforo bajo.
• El manejo de errores. Que RecursoNoEncontrado acabe siendo un 404 con el formato { error: { codigo, mensaje, estado, detalles } }.
• Casos límite y frontera. Vender exactamente las últimas entradas, vender una más, cantidad cero, cantidad negativa.
• Todo fallo que haya ocurrido en producción. Antes de arreglarlo, una prueba que lo reproduzca. Volveremos a esto en 09-06.

No se prueba (o se prueba muy poco):

• Getters triviales. Si get precioEuros() { return this.precioCentimos / 100; } merece una prueba es discutible; si tuviera redondeo, sí, porque ahí hay una decisión.
• Librerías de terceros. No es tu trabajo comprobar que Express enruta o que bcrypt hashea. Sí lo es comprobar cómo las usas.
• Configuración estática. Que PERMISOS tenga cinco claves no dice nada; que un rol pueda o no usarlas, sí.
• Detalles de implementación. Que un método llame internamente a otro método privado no es un comportamiento; es una decisión que quieres poder cambiar.
• Código generado. Migraciones autogeneradas, ficheros de arranque triviales.

Cuatro propiedades, en orden de importancia:

1. Rápida. Si la batería unitaria tarda más de unos segundos, dejarás de ejecutarla mientras programas.
2. Determinista. El mismo código con la misma entrada da siempre el mismo resultado. Nada de Date.now(), Math.random(), red o dependencia del orden. Todo eso lo domesticaremos con Sinon en 09-03.
3. Aislada. No depende de que otra prueba se haya ejecutado antes ni deja residuos para la siguiente.
4. Con un solo motivo de fallo. Cuando se pone roja, debe quedar claro qué comportamiento se rompió.

Y una quinta que no es técnica pero decide si la batería sobrevive: el nombre debe describir el comportamiento esperado, no el método invocado. El nombre es lo único que verás en la salida cuando falle a las tres de la mañana.

Fíjate en que todos los nombres buenos empiezan por un verbo en tercera persona y describen el efecto observable. Leídos junto al describe que los contiene forman una frase: Sesion vender — lanza ConflictoDeEstado si no quedan localidades suficientes.

Hay dos fallos de calidad que arruinan baterías enteras.

Prueba frágil es la que se rompe cuando el código cambia sin que el comportamiento cambie. Casi siempre nace de probar la implementación en lugar del comportamiento:

Falso positivo (o falso verde) es la prueba que pasa siempre, incluso con el código roto. Es peor que no tener prueba, porque genera confianza infundada. Las causas más habituales en Node:

• Una promesa no esperada: el it termina antes de que la aserción se ejecute. Lo veremos en detalle en 09-02.
• Una aserción dentro de un catch que nunca se ejecuta.
• Simular tanto la dependencia que la prueba solo comprueba tus propias suposiciones (el peligro central de 09-03).

Truco profesional que usaremos varias veces en el módulo: cuando escribas una prueba, rómpela a propósito. Cambia un signo en el código de producción y comprueba que se pone roja. Una prueba que nunca has visto fallar no es una prueba, es una esperanza.

El desarrollo dirigido por pruebas (Test-Driven Development) invierte el orden habitual: primero la prueba, después el código.

Un ciclo completo sobre una regla real de Escena Viva: ningún pedido puede superar las 6 entradas por sesión.

Rojo. Escribimos la prueba antes de que exista la comprobación:

Ejecutamos y falla. Este paso no es burocracia: verifica que la prueba sabe detectar el fallo. Si pasara ya en rojo, la prueba estaría mal escrita.

Verde. El código mínimo que la satisface:

Refactor. Ahora sí mejoramos: extraemos MAXIMO_POR_PEDIDO a una constante exportada para que el esquema zod y el mensaje de error usen el mismo número, y añadimos el detalles del error con el máximo permitido. La prueba nos protege durante el cambio.

Y ahora la honestidad prometida:

No es una religión. En este curso escribiremos algunas pruebas antes y muchas después, y en 09-06 usaremos TDD de forma estricta para una cosa concreta en la que es indiscutible: reproducir un fallo antes de arreglarlo.

El ejecutor nativo merece un párrafo honesto. Desde Node 20 es estable y perfectamente utilizable:

Si empezaras un proyecto nuevo hoy, node:test es una elección defendible y sin dependencias.

Por qué este curso usa Mocha + Chai + Sinon + supertest: porque es la pila más extendida en las APIs de Node que te vas a encontrar en producción, porque separa con claridad las tres responsabilidades (ejecutar, afirmar, simular) y eso enseña mejor los conceptos, porque su documentación de errores es explícita, y porque las ideas se trasladan a cualquier otra pila en una tarde. Elegida la pila, no cambiaremos a mitad del módulo: mezclar ejecutores es una fuente clásica de confusión.

Este es el recorrido del módulo:

La estructura de carpetas que crearemos, espejo de src/:

Tres convenciones que seguiremos sin excepción:

• Sufijo .test.js en todos los ficheros de prueba: hace trivial el patrón de búsqueda de Mocha y distingue las pruebas de las ayudas.
• Espejo del código fuente: src/dominio/sesion.js se prueba en test/unidad/sesion.test.js. Encontrar la prueba de un fichero nunca debe requerir una búsqueda.
• test/ayudas/ no contiene pruebas, solo utilidades compartidas: fábricas de datos y la ayuda de autenticación que resolverá la promesa del módulo 8.

• Escribir pruebas para subir un número. La cobertura es un indicador, no un objetivo. Lo trataremos a fondo en 09-05, pero interiorízalo ya: una prueba que ejecuta código sin comprobar nada sube la cobertura y no protege de nada.
• Empezar por las pruebas de extremo a extremo porque "prueban de verdad". Acabarás con el cono de helado y una batería que nadie ejecuta.
• Probar métodos privados. Si sientes esa necesidad, normalmente esa lógica quiere ser una función pública en otro módulo. #vendidas se prueba a través de libres y agotada.
• Pruebas que dependen del orden. "Funciona si ejecutas todo el fichero pero falla sola" es el síntoma. Cada it debe poder ejecutarse en solitario.
• Reutilizar objetos entre pruebas para "no repetir". Compartir un objeto mutable entre it es la causa número uno de pruebas intermitentes. Usa fábricas que devuelvan objetos nuevos.
• Consejo: empieza por la capa de mayor riesgo y menor coste. En Escena Viva eso es src/autorizacion/politica.js: funciones puras, sin dependencias, protegiendo lo más sensible del sistema. Se prueba entera en cincuenta líneas.
• Consejo: trata el código de las pruebas como código de producción. Se lee más veces de las que se escribe y hay que mantenerlo.

Para cada comportamiento de Escena Viva, indica a qué nivel de la pirámide lo probarías y por qué:

1. El total de un pedido de 2 entradas a 2500 céntimos es 5000.
2. POST /api/pedidos sin cabecera Authorization devuelve 401.
3. Un organizador de org-boveda no puede editar evt-001, que pertenece a org-almendra.
4. El middleware limiteCompra se aplica antes que el controlador de pedidos.
5. hashearContrasena usa coste 12.

Reescribe estos nombres de prueba siguiendo las reglas de la lección:

1. test comprarEntradas
2. politica funciona bien
3. error 409
4. no peta con cantidad 0

Escribe (en pseudocódigo, sin ejecutar) el ciclo rojo-verde-refactor para esta regla nueva: una sesión que ya ha comenzado no admite ventas. Indica qué prueba escribirías primero, qué código mínimo la haría pasar y qué refactorizarías después.

Ejercicio 1

1. Unitaria. Es un cálculo puro en el dominio; no necesita HTTP ni base de datos.
2. Integración. El 401 nace de la combinación ruta + middleware autenticar + manejadorDeErrores. Ninguna prueba unitaria del middleware garantiza que esté realmente montado en esa ruta.
3. Unitaria, con puedeGestionarEvento, porque es una función pura y podemos recorrer la matriz entera barata y exhaustivamente. Además una prueba de integración de confirmación (403 real por HTTP), no las treinta.
4. Integración. El orden de los middlewares solo es observable ejecutando la aplicación real: es exactamente lo que las pruebas unitarias no pueden ver.
5. Ninguna, o casi. Es una constante de configuración. Probar el coste exacto de bcrypt es probar la librería; sí tiene sentido una prueba de que verificarContrasena acepta el hash que produce hashearContrasena (comportamiento, no detalle).

Ejercicio 2

1. crea un pedido con estado pendiente y descuenta el aforo de la sesion
2. permite al administrador gestionar cualquier evento
3. devuelve ConflictoDeEstado si las localidades libres son menores que las solicitadas
4. lanza ErrorDeValidacion si la cantidad es cero

Ejercicio 3

Rojo: prueba rechaza la venta si la sesion ya ha comenzado, que crea una sesión con inicio en el pasado, llama a vender(1) y espera un ConflictoDeEstado. Falla porque vender no mira la fecha.

Verde: añadir al principio de vender una comprobación if (new Date(this.inicio) <= new Date()) { throw new ConflictoDeEstado('La sesion ya ha comenzado'); }.

Refactor: extraer un getter get haComenzado() que encapsule la comparación, reutilizable por el catálogo para no listar sesiones pasadas, e inyectar el reloj en lugar de llamar a new Date() directamente. Ese último punto es justo lo que hace posible la lección 09-03: el código que depende del reloj real no se puede probar de forma determinista.

Hemos puesto los cimientos. Sabemos por qué se prueba —para poder cambiar el código sin miedo, no por si acaso—, cómo se estructura una prueba con preparar, actuar y comprobar, qué niveles existen y por qué la pirámide tiene la forma que tiene, qué merece prueba según el riesgo y qué no, qué propiedades hacen buena a una prueba, cómo distinguir una prueba frágil de una robusta, cuándo TDD ayuda de verdad y qué herramientas hay en el ecosistema de Node.

También tenemos el plan: test/unidad/, test/integracion/, test/ayudas/, ficheros *.test.js, y la pila Mocha + Chai + Sinon + supertest.

Lo que no tenemos todavía es una sola línea ejecutable. En la lección siguiente, Pruebas Unitarias con Mocha y Chai, instalamos la pila, arreglamos de una vez el script test que lleva cuatro módulos fallando a propósito, y escribimos la batería unitaria completa del dominio de Escena Viva, incluida esa tabla de casos que recorre la matriz de permisos celda por celda que llevamos prometiendo desde el módulo 8.