Mejores Prácticas de Pruebas

Reglas que mantienen las suites de pruebas de la API de Node rápidas, fiables y centradas en el comportamiento observable.

Cómo Usar Esta Lista

• Aplícala al añadir la primera prueba a un nuevo servicio.
• Revísala durante las PR que añaden mocks o infraestructura de integración.
• Hazla cumplir a través de CI (se requiere npm test, trabajo de integración separado).

A - Diseño de Pruebas

• Prueba el comportamiento, no la implementación privada. Afirma el estado HTTP, el JSON devuelto y los efectos secundarios, no el orden de las llamadas internas.
• Sigue la pirámide: muchas unitarias, menos de integración, raras E2E. La mayoría de las pruebas se completan en milisegundos.
• Nombra las pruebas como especificaciones. devuelve 409 cuando la factura ya está pagada es mejor que test1.
• Un enfoque de aserción principal por prueba. Múltiples aserciones están bien cuando se verifica un único resultado de comportamiento.
• Casos basados en tablas para variaciones de entrada. Cubre casos extremos sin copiar y pegar pruebas.

B - HTTP y Estructura de la Aplicación

• Exporta createApp() sin auto-escucha. Supertest y Fastify inject necesitan aplicaciones en proceso.
• Cubre rutas de error: manejadores 400, 401, 404, 409, 500. Las suites solo de ruta feliz omiten regresiones.
• Usa Supertest o Fastify inject, no puertos aleatorios. Evita EADDRINUSE y CI inestable.
• No accedas a URLs de producción en las pruebas. Solo staging o en proceso.
• Congela el tiempo al probar la lógica de TTL/caducidad. vi.setSystemTime o interfaz de reloj inyectada.

C - Datos y Aislamiento

• Aísla la base de datos por trabajo o suite de CI. Testcontainers o esquema dedicado; nunca una base de datos de desarrollo compartida.
• Trunca o revierte entre pruebas de integración. Evita fallos dependientes del orden.
• Usa fábricas/constructores para entidades de prueba. Configuración legible sin 50 líneas de fixtures en línea.
• Siembra datos mínimos por prueba. Grandes fixtures compartidos ocultan qué campo causó el fallo.
• Ejecuta migraciones contra la base de datos de prueba igual que en producción. Detecta diferencias SQL tempranamente.

D - Herramientas y CI

• Una sola entrada npm test; divide unitarias vs integración cuando sea necesario. test:integration puede requerir Docker.
• Prefiere node:test o Vitest para código nuevo; planifica la salida de Jest en brownfield. Evita tres ejecutores.
• Ejecuta pruebas en cada PR después de typecheck y lint. Fallo rápido en el orden de la pipeline.
• No fusiones pruebas inestables. Ponlas en cuarentena con un ticket del propietario y una fecha de caducidad, o arréglalas inmediatamente.
• Pruebas de contrato para dependencias HTTP entre servicios. Pact o diff de esquema antes del despliegue.

E - Carga y Lanzamiento

• k6/Artillery smoke en staging antes de lanzamientos importantes. Umbrales de p95 y tasa de error definidos.
• Prueba de carga de rutas de escritura con estrategia de limpieza. Prefijos idempotentes o inquilino dedicado.
• Mide la cobertura; no adores el 100%. Módulos de dominio críticos objetivo; código generado excluido.
• Prueba el middleware de autenticación con tokens realistas. No auth disabled in test globalmente a menos que sea una unidad aislada.
• Documenta cómo ejecutar pruebas de integración localmente. Prerrequisito de Docker en el README.

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Pruebas - introducción a la pirámide
• Supertest e Integración HTTP - HTTP en proceso
• Testcontainers - Postgres/Redis reales

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.