Integration Testing con Testcontainers

Tests de integración que se ejecutan contra dependencias reales y efímeras —un Postgres levantado en un contenedor Docker descartable— en lugar de mocks. Construido con Testcontainers, TypeScript, Vitest y node-postgres.

---

Resumen ejecutivo

Qué es	Una suite de integración que prueba la capa de datos contra una base de datos real, aislada y descartable, creada automáticamente para cada corrida.
Problema que resuelve	Los mocks de base de datos devuelven lo que uno programa; ocultan errores reales de SQL, violaciones de constraints y comportamiento de tipos. Una base compartida, por su parte, arrastra estado sucio entre corridas.
Enfoque	Testcontainers levanta un Postgres real en un contenedor efímero, aplica el esquema, y los tests corren contra él con aislamiento por test; al terminar, el contenedor se destruye.
Resultado	Fidelidad de la base real (constraints UNIQUE/CHECK, defaults, tipos NUMERIC) con el aislamiento de un entorno limpio en cada corrida. 6 tests verdes en ~6 s.
Stack	Testcontainers · PostgreSQL · Vitest · node-postgres · TypeScript

---

Cómo funciona

flowchart LR
    A["beforeAll:<br/>levantar contenedor<br/>Postgres real"] --> B["aplicar esquema<br/>(migración)"]
    B --> C["Tests:<br/>repositorio contra<br/>la base real"]
    C --> D["afterAll:<br/>destruir contenedor"]
    C -.->|beforeEach: TRUNCATE| C
    style C fill:#1a3a5c,color:#fff

Loading

• Contenedor efímero: cada corrida arranca con una instancia limpia de postgres:16-alpine; al terminar, se destruye sin dejar rastro.
• Esquema real: se aplica src/db/schema.sql sobre la base, validando la migración de verdad.
• Aislamiento por test: un TRUNCATE antes de cada test garantiza independencia (habilita ejecución confiable).

---

Qué detecta un mock no vería

Los tests validan comportamiento que solo aparece contra una base real:

Test	Qué verifica
Round-trip create/find	La persistencia real y el default status = PENDING que aplica Postgres
Constraint UNIQUE	Insertar una reference duplicada falla
Constraint CHECK	Un total_price negativo falla
Tipo NUMERIC	El precio vuelve correctamente convertido a número
Update / delete	Cambios de estado y baja real, verificando el efecto

---

Estructura

src/
├── db/schema.sql              # migración (se aplica sobre el Postgres real)
└── repository/bookings.ts     # capa de datos bajo prueba
tests/
└── bookings.repository.test.ts # integración contra Postgres real (Testcontainers)

---

Uso

Requiere un runtime de contenedores (Docker) disponible.

npm install
npm test          # levanta el contenedor, corre los tests, lo destruye
npm run typecheck

Entorno local con colima (VM Linux headless, alternativa a Docker Desktop):

colima start
export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"
export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE="/var/run/docker.sock"
npm test

En CI (runners con Docker nativo) funciona sin configuración adicional.

---

Documentación técnica

docs/DOCUMENTACION-TECNICA.md detalla: por qué la base real vs mocks, el ciclo de vida del contenedor, el aislamiento entre tests, la validación de constraints y migraciones, la configuración con colima, y las vías de extensión (otras dependencias como Kafka/Redis, contenedores compartidos entre archivos).

---

La suite completa

Este repositorio forma parte de una suite de automatización de calidad que cubre el ciclo de testing de punta a punta, de los fundamentos a las prácticas propias de un rol SDET.

Fundamentos

1. Framework E2E de UI — Playwright · Page Object Model
2. Testing de API — contract testing con Zod
3. Pipeline CI/CD — GitHub Actions · quality gates
4. Estabilidad y flakiness — detección y erradicación
5. Regresión visual & contract testing — Playwright + Pact

Avanzado (SDET)

6. Performance & load testing — k6 · thresholds como gate
7. Integración con dependencias reales — este repositorio
8. DevSecOps — SAST · SCA · DAST en el pipeline
9. Tooling interno de QA — test impact + flaky detection
10. Evals de aplicaciones con IA — LLM testing

---

Licencia

MIT.