DevOps ·

Playwright + Testcontainers: E2E reales con DB efímera y gates de coverage

Las pruebas end-to-end suelen morir por dos razones: dependen de un entorno compartido que nadie controla, o se ejecutan contra una base de datos "de staging" que ya tiene datos inconsistentes. El resultado es familiar: flaky tests, falsos verdes y un pipeline que la gente aprende a ignorar. La combinación de Playwright con Testcontainers ataca ese problema de raíz: cada ejecución levanta su propia base de datos efímera, con esquema y datos controlados, y la destruye al terminar. Sobre esa base se pueden aplicar gates de coverage reales que bloquean el merge cuando la calidad baja.

Por qué Testcontainers cambia la ecuación

Testcontainers es una librería que orquesta contenedores Docker desde el propio código de pruebas. En lugar de conectar a un Postgres externo, tu suite declara: "quiero un Postgres 16 limpio, con este esquema aplicado y estos seeds cargados". El contenedor nace, se usa y se destruye en el mismo ciclo de vida del test. Esto elimina la clase de bugs más molesta del E2E: el estado compartido entre ejecuciones.

Ventajas concretas frente a un entorno fijo:

  • Aislamiento total: cada suite tiene su propia instancia, sin colisiones de datos.
  • Reproducibilidad: la misma imagen de Postgres en local, en CI y en la máquina de un compañero.
  • Paralelización segura: varios workers pueden correr en paralelo sin pisarse.
  • Migraciones reales: se prueban las migraciones de verdad, no un dump desactualizado.

Arquitectura del setup

El patrón habitual es un global setup de Playwright que arranca el contenedor, aplica migraciones, siembra datos y expone la cadena de conexión vía variables de entorno. Luego, los tests de Playwright la consumen a través de process.env o de un fixture personalizado.

// global-setup.ts
import { PostgreSqlContainer } from '@testcontainers/postgresql';
import { execSync } from 'node:child_process';

export default async function globalSetup() {
  const pg = await new PostgreSqlContainer('postgres:16-alpine')
    .withDatabase('app_test')
    .withUsername('test')
    .withPassword('test')
    .withExposedPorts(5432)
    .start();

  const url = pg.getConnectionUri();
  process.env.DATABASE_URL = url;

  // Aplicar migraciones reales contra la DB efímera
  execSync('npx prisma migrate deploy', {
    env: { ...process.env, DATABASE_URL: url },
    stdio: 'inherit',
  });

  // Sembrar datos mínimos para los tests
  execSync('npx tsx scripts/seed-test.ts', {
    env: { ...process.env, DATABASE_URL: url },
    stdio: 'inherit',
  });

  // Guardar handle para teardown
  (globalThis as any).__PG__ = pg;
}

El globalTeardown correspondiente llama a pg.stop(). Si el proceso muere a mitad, Testcontainers tiene Ryuk, un contenedor reaper que limpia los recursos huérfanos. Es una de esas cosas que uno agradece cuando un job de CI se cancela abruptamente.

Playwright apuntando al stack efímero

El segundo contenedor suele ser la propia aplicación. Aquí hay dos enfoques: levantar el servidor con webServer de Playwright (más simple), o containerizar la app también. Para muchos equipos el primer camino es suficiente y más rápido:

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  globalSetup: './global-setup.ts',
  globalTeardown: './global-teardown.ts',
  webServer: {
    command: 'npm run start:test',
    url: 'http://localhost:3000/health',
    reuseExistingServer: !process.env.CI,
    env: { DATABASE_URL: process.env.DATABASE_URL! },
  },
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  reporter: [['html'], ['json', { outputFile: 'reports/e2e.json' }]],
});

El flag reuseExistingServer evita reiniciar el server en desarrollo, pero en CI siempre arranca limpio. La traza en el primer reintento es oro puro para depurar flakiness sin reproducir localmente.

Coverage: no solo de unit tests

Un error común es medir coverage únicamente con Jest o Vitest. Eso deja fuera todo el código que solo se ejecuta en el flujo integrado: handlers de API, middlewares, capas de persistencia. Playwright puede recolectar coverage de V8 mientras corre el navegador, pero para un E2E "real" lo interesante es medir también el backend.

Con Node, la forma más limpia es arrancar la app con NODE_V8_COVERAGE apuntando a un directorio, y luego fusionar los reportes:

NODE_V8_COVERAGE=./coverage/e2e \
DATABASE_URL=$DATABASE_URL \
node --import tsx ./src/server.ts

Tras la suite, se usa c8 para consolidar:

npx c8 report \
  --temp-directory=./coverage/e2e \
  --reporter=text --reporter=lcov \
  --check-coverage \
  --lines 80 --functions 75 --branches 70

El comando anterior falla con código distinto de cero si no se alcanzan los umbrales. Ese es, literalmente, el gate. No hay magia: si el coverage baja, el job falla y el PR se bloquea.

Gates de coverage en CI

Un workflow de GitHub Actions que integra todo podría verse así:

name: e2e
on: [pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - name: Ejecutar E2E con DB efímera
        run: npx playwright test
      - name: Gate de coverage
        run: npx c8 report --temp-directory=./coverage/e2e \
             --check-coverage --lines 80 --functions 75
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/

Detalles que marcan la diferencia en producción:

  • Umbrales por carpeta: no es lo mismo exigir 80% en src/api que en src/utils. c8 y nyc permiten --per-file para evitar que un archivo enorme esconda otro sin cobertura.
  • Comparación contra baseline: en lugar de un umbral fijo, guardar el coverage de main y fallar si el PR baja más de X puntos. Herramientas como Codecov o Coveralls facilitan esto; también se puede hacer con un script propio que lea coverage-summary.json.
  • Coverage combinado: fusionar unit + E2E en un solo reporte da una foto más honesta. c8 merge acepta múltiples directorios temporales.
  • Tiempos: Testcontainers agrega ~5-10 segundos por arranque. Con reuseExistingServer local y caché de imágenes Docker en CI (docker pull previo), el impacto es mínimo.

Errores frecuentes y cómo evitarlos

No limpiar entre tests. Aunque la DB sea efímera por suite, si un test crea un usuario y otro asume que no existe, vas a tener flakes. Usa transacciones por test o un truncate en beforeEach.

Ignorar el orden de migraciones. Correr migrate deploy contra un contenedor recién nacido es lo más cercano a producción. Si falla, es un bug real, no del entorno.

Medir coverage sin excluir archivos triviales. Configura .c8rc con exclude para **/*.d.ts, **/migrations/** y similares. De lo contrario, el gate se vuelve ruidoso y la gente lo desactiva.

Olvidar los artefactos. En CI, subir siempre playwright-report y coverage/lcov-report, incluso cuando el job falla. Sin eso, depurar un PR rojo se vuelve arqueología.

Conclusión

La combinación de Play