Matware E2E Runner

Con el pool de Docker, Chrome se ejecuta dentro de un contenedor, por lo que localhost allí significa el contenedor — no tu máquina. host.docker.internal conecta con tu host. En Linux (Docker Engine, no Docker Desktop) agrega --add-host=host.docker.internal:host-gateway, o usa tu IP de LAN. Las opciones 1 y 2 no tienen esto — el navegador es local, así que localhost simple funciona.

cp node_modules/@matware/e2e-runner/opencode.json ./
mkdir -p .opencode && cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/

Consulta OPENCODE.md para más detalles.

Cada archivo .json en e2e/tests/ contiene un array de pruebas. Cada prueba tiene un name y actions secuenciales:

[
  {
    "name": "homepage-loads",
    "actions": [
      { "type": "goto", "value": "/" },
      { "type": "assert_visible", "selector": "body" },
      { "type": "assert_url", "value": "/" },
      { "type": "screenshot", "value": "homepage.png" }
    ]
  }
]

Los archivos de suite pueden tener prefijos numéricos para ordenar (01-auth.json, 02-dashboard.json). La bandera --suite coincide con o sin el prefijo, así que --suite auth encuentra 01-auth.json.

Clic por texto — cuando click usa text en lugar de selector, busca en elementos interactivos y de contenido comunes:

button, a, [role="button"], [role="tab"], [role="menuitem"], [role="option"],
[role="listitem"], div[class*="cursor"], span, li, td, th, label, p, h1-h6

{ "type": "click", "text": "Sign In" }

Estas acciones manejan patrones comunes en aplicaciones React/MUI que normalmente requieren plantilla verbosa de evaluate:

// Before: 5 lines of evaluate boilerplate
{ "type": "evaluate", "value": "const input = document.querySelector('#search'); const nativeSet = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set; nativeSet.call(input, 'term'); input.dispatchEvent(new Event('input', {bubbles: true})); input.dispatchEvent(new Event('change', {bubbles: true}));" }

// After: 1 action
{ "type": "type_react", "selector": "#search", "value": "term" }

Todas las acciones posteriores se ejecutan en la pestaña activa:

{ "type": "click", "text": "Open report" }
{ "type": "wait_for_tab", "text": "report" }
{ "type": "assert_text", "text": "Quarterly results" }
{ "type": "close_tab" }

Reintento a nivel de prueba — reintenta una prueba completa en caso de fallo. Configúralo globalmente mediante configuración o por prueba:

{ "name": "flaky-test", "retries": 3, "timeout": 15000, "actions": [...] }

Las pruebas que pasan después del reintento se marcan como flaky en el informe y el sistema de aprendizaje.

Reintento a nivel de acción — reintenta una sola acción sin volver a ejecutar toda la prueba. Útil para clics y esperas sensibles al tiempo:

{ "type": "click", "selector": "#dynamic-btn", "retries": 3 }
{ "type": "wait", "selector": ".lazy-loaded", "retries": 2 }

Configúralo globalmente: actionRetries en la configuración, --action-retries <n> CLI, o variable de entorno ACTION_RETRIES. Retraso entre reintentos: actionRetryDelay (predeterminado 500ms).

Las pruebas que comparten estado (p. ej., dos pruebas que modifican el mismo registro) pueden competir cuando se ejecutan en paralelo. Márcalas como seriales:

{ "name": "create-patient", "serial": true, "actions": [...] }
{ "name": "verify-patient-list", "serial": true, "actions": [...] }

Las pruebas seriales se ejecutan una a la vez después de que todas las pruebas paralelas terminen — evitando interferencias sin ralentizar las pruebas independientes.

El enfoque más simple — inicia sesión a través de la interfaz de usuario como un usuario real:

{
  "hooks": {
    "beforeEach": [
      { "type": "goto", "value": "/login" },
      { "type": "type", "selector": "#email", "value": "test@example.com" },
      { "type": "type", "selector": "#password", "value": "test-password" },
      { "type": "click", "text": "Sign In" },
      { "type": "wait", "selector": ".dashboard" }
    ]
  },
  "tests": [...]
}

Para SPA con JWT, omite el formulario de inicio de sesión inyectando el token directamente:

{ "type": "set_storage", "value": "accessToken=eyJhbGciOiJIUzI1NiIs..." }

O configúralo globalmente en la configuración:

// e2e.config.js
export default {
  authToken: 'eyJhbGciOiJIUzI1NiIs...',
  authStorageKey: 'accessToken',
};

Cada prueba se ejecuta en un contexto de navegador nuevo, por lo que el estado de autenticación está automáticamente limpio entre pruebas.

Más estrategias: Autenticación basada en cookies, inyección de encabezados HTTP, omisiones de OAuth/SSO, módulos de autenticación reutilizables y pruebas basadas en roles — consulta docs/authentication.md

Extrae flujos comunes en módulos parametrizados:

// e2e/modules/login.json
{
  "$module": "login",
  "description": "Log in via the UI login form",
  "params": {
    "email": { "required": true, "description": "User email" },
    "password": { "required": true, "description": "User password" }
  },
  "actions": [
    { "type": "goto", "value": "/login" },
    { "type": "type", "selector": "#email", "value": "{{email}}" },
    { "type": "type", "selector": "#password", "value": "{{password}}" },
    { "type": "click", "text": "Sign In" },
    { "type": "wait", "value": "2000" }
  ]
}

Úsalos en pruebas:

{
  "name": "dashboard-loads",
  "actions": [
    { "$use": "login", "params": { "email": "user@test.com", "password": "secret" } },
    { "type": "assert_text", "text": "Dashboard" }
  ]
}

Los módulos admiten validación de parámetros (los parámetros requeridos fallan rápidamente), bloques condicionales ({{#param}}...{{/param}}), composición anidada y detección de ciclos.

Ejecuta acciones en puntos del ciclo de vida. Defínelos globalmente en la configuración o por suite:

{
  "hooks": {
    "beforeAll": [{ "type": "goto", "value": "/setup" }],
    "beforeEach": [{ "type": "goto", "value": "/" }],
    "afterEach": [{ "type": "screenshot", "value": "after.png" }],
    "afterAll": []
  },
  "tests": [...]
}

Importante: beforeAll se ejecuta en una página de navegador separada que se cierra antes de que comiencen las pruebas. Usa beforeEach para el estado que las pruebas necesitan (cookies, localStorage, tokens de autenticación).

Omite pruebas exploratorias o borradores de las ejecuciones de --all:

// e2e.config.js
export default {
  exclude: ['explore-*', 'debug-*', 'draft-*'],
};

Las ejecuciones de suites individuales (--suite) no se ven afectadas por los patrones de exclusión.

claude plugin marketplace add fastslack/mtw-e2e-runner
claude plugin install e2e-runner@matware

Esto le da a Claude 17 herramientas MCP, una habilidad de flujo de trabajo, 4 comandos de barra (/e2e-runner:run, /e2e-runner:create-test, /e2e-runner:verify-issue, /e2e-runner:capture) y 3 agentes especializados (test-analyzer, test-creator, test-improver).

Instalación solo MCP (solo herramientas, sin habilidad/comandos/agentes):

claude mcp add --transport stdio --scope user e2e-runner \
  -- npx -y -p @matware/e2e-runner e2e-runner-mcp

cp node_modules/@matware/e2e-runner/opencode.json ./
mkdir -p .opencode && cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/

Consulta OPENCODE.md para más detalles.

El inicio/detención del grupo es solo CLI — no se expone a través de MCP.

Describe cómo debería verse la página — la IA juzga aprobado/fallido a partir de capturas de pantalla:

{
  "name": "dashboard-loads",
  "expect": "Patient list with at least 3 rows, no error messages, sidebar with navigation links",
  "actions": [
    { "type": "goto", "value": "/dashboard" },
    { "type": "wait", "selector": ".patient-list" }
  ]
}

Después de que las acciones de prueba se completen, el ejecutor captura automáticamente una captura de pantalla de verificación. La respuesta MCP incluye el hash de la captura de pantalla — Claude Code la recupera y verifica visualmente contra tu descripción de expect. No se requiere clave API.

Cómo funciona:

1. Obtener — Extrae los detalles del issue (título, cuerpo, etiquetas) mediante gh o glab CLI
2. Generar — La IA crea acciones de prueba JSON basadas en la descripción del issue
3. Ejecutar — Opcionalmente ejecuta las pruebas inmediatamente para verificar si un bug es reproducible

# Fetch and display
e2e-runner issue https://github.com/owner/repo/issues/42

# Generate a test file via Claude API
e2e-runner issue https://github.com/owner/repo/issues/42 --generate

# Generate + run + report
e2e-runner issue https://github.com/owner/repo/issues/42 --verify
# -> "BUG CONFIRMED" or "NOT REPRODUCIBLE"

En Claude Code, solo pregunta:

"Obtén el issue #42 y crea pruebas E2E para él"

Lógica de verificación de bugs: Las pruebas generadas verifican el comportamiento correcto. Falla de prueba = bug confirmado. Todas las pruebas pasan = no reproducible.

Autenticación: GitHub requiere gh CLI, GitLab requiere glab CLI. Se admite GitLab autoalojado.

Ejecución en vivo — monitorea pruebas en tiempo real con progreso paso a paso, duraciones y recuento de workers activos.

Suites de pruebas — explora todas las suites en todos los proyectos. Ejecuta una sola suite o todas las pruebas con un clic.

Historial de ejecuciones — sigue las tendencias de tasa de aprobación con el gráfico integrado. Haz clic en cualquier fila para expandir el detalle completo.

Detalle de ejecución — insignias PASS/FAIL, miniaturas de capturas de pantalla con hashes copiables (ss:77c28b5a), errores de consola formateados y registros de solicitudes de red.

Galería de capturas — explora todas las capturas de pantalla con búsqueda por hash (capturas de acciones, errores y verificaciones).

Estado del pool — salud del pool de Chrome: espacios disponibles, sesiones en ejecución, presión de memoria.

El runner aprende de cada ejecución de prueba — acumulando conocimiento sobre tu suite de pruebas con el tiempo. Consulta información mediante la herramienta MCP e2e_learnings:

Almacenamiento y exportación:

• SQLite (~/.e2e-runner/dashboard.db) — predeterminado, sin configuración
• Grafo de conocimiento Neo4j — opcional, para análisis basado en relaciones. Gestiona mediante la herramienta MCP e2e_neo4j o docker compose
• Informe Markdown (e2e/learnings.md) — generado automáticamente después de cada ejecución

Narración de pruebas: Cada ejecución de prueba genera una narrativa legible por humanos de lo que sucedió paso a paso, visible en la salida CLI y en el panel de control.

Aserción explícita — coloca assert_no_network_errors después de cargas críticas de página:

{ "type": "goto", "value": "/dashboard" },
{ "type": "wait", "selector": ".loaded" },
{ "type": "assert_no_network_errors" }

Bandera global — establece failOnNetworkError: true para fallar automáticamente cualquier prueba con errores de red:

e2e-runner run --all --fail-on-network-error

Cuando está deshabilitada (predeterminado), el runner aún recopila e informa errores de red — la respuesta MCP incluye una advertencia cuando las pruebas pasan pero tienen errores de red.

Registro de red completo — todas las solicitudes XHR/fetch se capturan con URL, método, estado, duración, encabezados de solicitud/respuesta y cuerpo de respuesta (truncado a 50KB). Visible en el panel de control con filas de detalle de solicitud expandibles.

Flujo de profundización MCP:

1. e2e_run          → compact networkSummary + runDbId
2. e2e_network_logs(runDbId)                     → all requests (url, method, status, duration)
3. e2e_network_logs(runDbId, errorsOnly: true)   → only failed requests
4. e2e_network_logs(runDbId, includeHeaders: true) → with headers
5. e2e_network_logs(runDbId, includeBodies: true)  → full request/response bodies

La respuesta de e2e_run se mantiene compacta (~5KB) independientemente de cuántas solicitudes se hayan capturado. Usa e2e_network_logs con el runDbId devuelto para profundizar en los detalles bajo demanda.

Captura pantallas de cualquier URL bajo demanda — no se requiere suite de pruebas:

e2e-runner capture https://example.com
e2e-runner capture https://example.com --full-page --selector ".loaded" --delay 2000

Mediante MCP, la herramienta e2e_capture admite authToken y authStorageKey para páginas autenticadas — inyecta el token en localStorage antes de navegar.

Cada captura obtiene un hash determinista (ss:a3f2b1c9). Usa e2e_screenshot para recuperar cualquier captura por hash — devuelve la imagen con metadatos (nombre de prueba, paso, tipo).

{
  "tests": [
    {
      "name": "checkout flow (heavy JS, real Chrome)",
      "driver": "browserless",
      "actions": [...]
    },
    {
      "name": "scrape product page (lightweight)",
      "driver": "obscura",
      "fallbackDriver": "cdp",
      "actions": [...]
    }
  ]
}

driver es opcional. Si se establece, solo los pools cuyo controlador detectado coincida se convierten en candidatos. fallbackDriver es opt-in explícito — sin él, un controlador objetivo faltante falla la prueba con un mensaje claro. La ocupación del pool no activa el respaldo; el runner espera dentro del conjunto filtrado.

Fuerza un controlador para una ejecución completa (los overrides de CLI ganan sobre los campos por prueba — útil para benchmarks A/B):

e2e-runner run --all --driver obscura
e2e-runner run --all --driver obscura --fallback-driver cdp

# browserless (default) — managed by `pool start`
e2e-runner pool start

# Lightpanda — pool start uses templates/docker-compose-lightpanda.yml
e2e-runner pool start                 # with poolDriver: 'lightpanda' in config

# Obscura — install the binary and run it yourself
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
tar xzf obscura-x86_64-linux.tar.gz
./obscura serve --port 9222 --stealth
# then point the runner at it: poolUrls: ['http://localhost:9222'], poolDriver: 'obscura'

# Run tests
e2e-runner run --all                  # All suites
e2e-runner run --suite auth           # Single suite
e2e-runner run --tests path/to.json   # Specific file
e2e-runner run --inline '<json>'      # Inline JSON

# Pool management (CLI only, not MCP)
e2e-runner pool start                 # Start Chrome container
e2e-runner pool stop                  # Stop Chrome container
e2e-runner pool status                # Check pool health

# Issue-to-test
e2e-runner issue <url>                # Fetch issue
e2e-runner issue <url> --generate     # Generate test via AI
e2e-runner issue <url> --verify       # Generate + run + report

# Dashboard
e2e-runner dashboard                  # Start web dashboard

# Other
e2e-runner list                       # List available suites
e2e-runner capture <url>              # On-demand screenshot
e2e-runner init                       # Scaffold project

Crea e2e.config.js en la raíz de tu proyecto:

export default {
  baseUrl: 'http://host.docker.internal:3000',
  concurrency: 4,
  retries: 2,
  actionRetries: 1,
  testTimeout: 30000,
  outputFormat: 'both',
  failOnNetworkError: true,
  exclude: ['explore-*', 'debug-*'],

  hooks: {
    beforeEach: [{ type: 'goto', value: '/' }],
  },

  environments: {
    staging: { baseUrl: 'https://staging.example.com' },
    production: { baseUrl: 'https://example.com', concurrency: 5 },
  },
};

Prioridad de configuración (gana la más alta):

1. Banderas CLI
2. Variables de entorno
3. Archivo de configuración (e2e.config.js o e2e.config.json)
4. Predeterminados

Cuando se establece --env <name>, el perfil coincidente anula todo.

e2e-runner run --all --output junit

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx e2e-runner pool start
      - run: npx e2e-runner run --all --output junit
      - uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: e2e/screenshots/junit.xml

import { createRunner } from '@matware/e2e-runner';

const runner = await createRunner({ baseUrl: 'http://localhost:3000' });

const report = await runner.runAll();
const report = await runner.runSuite('auth');
const report = await runner.runFile('e2e/tests/login.json');
const report = await runner.runTests([
  { name: 'quick-check', actions: [{ type: 'goto', value: '/' }] },
]);