Antes de escribir pruebas end-to-end en una API de Node.js, necesitas entender cómo está organizado el código. Aquí desglosamos una arquitectura basada en Clean Architecture que separa controladores, servicios y entidades para que tu aplicación sea mantenible, escalable y fácil de testear.

¿Qué es Clean Architecture aplicada a una API en Node.js?

La idea central es separar responsabilidades en capas. Los controladores exponen los endpoints, los servicios contienen la lógica de negocio y las entidades representan los datos que maneja Sequelize, el ORM que conecta con PostgreSQL [01:00].

Esta estructura no salió de la nada. Es la continuación de una serie de cuatro cursos de Node: fundamentos con Express, conexión a base de datos con migraciones y servicios, y seguridad con Passport y JWT. Ahora le sumamos pruebas automatizadas.

¿Por qué usar Clean Architecture en una API? Porque cada carpeta tiene una responsabilidad única. Eso hace que el código sea adaptable, fácil de mantener y, sobre todo, sencillo de testear cuando llegue el momento de escribir pruebas end-to-end.

¿Cómo se organizan las carpetas del proyecto?

Dentro de src encontramos una distribución pensada para que cada pieza haga una sola cosa bien. Vamos por partes.

¿Para qué sirven config y la carpeta de base de datos?

El archivo config lee todas las variables de entorno: el puerto, la URL de la base de datos, la API key, el JWT secret. Desde ahí se importan a cualquier punto de la aplicación [02:30].

La carpeta de base de datos contiene tres elementos clave:

• Las migraciones, que crean la estructura de las tablas (usuario, customer, categoría, producto, orden y la tabla ternaria order-product).
• Los modelos o entidades, gestionados por Sequelize, donde defines el esquema, las propiedades, si un campo es autoincremental o si es llave primaria.
• El archivo .sequelizerc, que indica qué modelos y migraciones usar cuando ejecutas npm run migrations desde la terminal.

Hay una distinción importante. El config maneja la conexión para correr migraciones desde la línea de comandos. El archivo Sequelize maneja la conexión que usa la aplicación en producción. Son dos contextos distintos con la misma base de datos.

¿Qué hacen los DTOs y los middlewares?

Los DTOs (también llamados schemas en otros cursos) validan la integridad de los datos en cada request. Si intentas crear un usuario con una contraseña de menos de ocho caracteres, el DTO te detiene ahí mismo. Para esto usamos Joi, una librería de validación que verifica formatos de correo, longitudes mínimas, tipos de dato y URLs válidas [05:00].

Los middlewares son interceptores que se ejecutan antes de llegar a la lógica del endpoint. Aquí encontrarás:

• Validación de autenticación con API key y verificación de rol.
• Protección de rutas según permisos, por ejemplo solo administradores.
• Manejo de errores con Boom, una librería para logging y respuestas de error consistentes.
• Validación automática de los schemas definidos en los DTOs.

¿Cómo se conectan rutas, servicios y modelos?

Las rutas son la parte tangible que se expone al público. Si una aplicación frontend o móvil quiere consumir tu API, este es el punto de entrada. Aquí defines los métodos GET, POST, PATCH y DELETE, y aplicas los middlewares necesarios.

Por ejemplo, antes de un PATCH a usuarios, validas el DTO. En el endpoint de perfil, exiges que el usuario esté autenticado. Las rutas orquestan, no ejecutan la lógica.

¿Cuál es la diferencia entre rutas y servicios? Las rutas exponen y validan. Los servicios ejecutan la lógica de negocio y hablan con la base de datos. Esa separación es lo que hace mantenible al proyecto.

Los servicios encarnan el modelo de negocio. Cuando el controlador valida los datos, los pasa al servicio, y ahí ocurre la magia: se crea el usuario, se busca, se actualiza o se elimina, conectando directamente con Sequelize y ejecutando queries sobre PostgreSQL [07:30].

Finalmente, las utilidades incluyen las strategies que usa Passport.js para autenticación. Está la estrategia local para login con usuario y contraseña, y la validación del access token JWT que se emite tras un login exitoso.

¿Por qué esta arquitectura facilita las pruebas end-to-end?

Cuando cada capa tiene una responsabilidad clara, agregar pruebas se vuelve natural. Puedes testear un servicio sin tocar las rutas, validar un middleware en aislamiento o ejecutar un flujo completo desde el endpoint hasta la base de datos.

La base de código sólida es el prerrequisito. Sin esa separación, cualquier prueba se convierte en un nudo de dependencias imposible de mantener.

En la siguiente lección haremos el setup inicial e instalaremos Jest, la herramienta que usaremos para escribir las pruebas. ¿Tú ya has trabajado con Clean Architecture en tus proyectos? Cuéntame en los comentarios cómo organizas tus carpetas.