Saltar a contenido

QA E2E

Plugin de testing End-to-End automatizado que valida criterios de aceptacion (ACs) de Feature Specs contra un servidor de pruebas usando Playwright MCP. Para cada AC que falla, crea un GitHub Issue estructurado con evidencia (screenshots, logs, pasos para reproducir). Cierra el gap entre la verificacion unitaria de ATL y la validacion real en browser que ve el usuario final.

Prerequisitos

  • Claude Code instalado
  • Playwright MCP configurado (claude mcp add playwright -- npx @anthropic-ai/mcp-playwright)
  • GitHub CLI (gh) instalado y autenticado (gh auth login)
  • Servidor de pruebas accesible (localhost o staging)
  • Feature Spec con ACs en formato Given/When/Then (generado por SDD-Wizards, SDD-Intake o ATL)
  • Variables de entorno configuradas segun la estrategia de auth elegida

Skills

QA E2E expone 2 skills que se ejecutan en secuencia: primero el wizard configura la sesion de testing, luego el runner ejecuta las pruebas y reporta resultados. Ambos usan context: fork para aislar su ventana de contexto y disable-model-invocation: true para evitar auto-activacion.

Skill Descripcion Invocacion Tools permitidos
qa-wizard Configura la sesion de testing: selecciona Feature Spec, URL del servidor, estrategia de auth. Genera .context/qa-e2e/config.json. /qa-e2e:qa-wizard [feature-name] Read, Write, Glob, Grep, Bash (echo, gh, mkdir, ls, cat), Engram (mem_save, mem_search, mem_context)
qa-run Orquesta la ejecucion E2E: autentica, ejecuta cada AC en browser, crea GitHub Issues por fallos, genera reporte final. /qa-e2e:qa-run [feature-name] Read, Write, Glob, Grep, Bash (echo, gh, curl, mkdir, ls, cat, date), Agent (qa-navigator, qa-reporter), Engram (mem_save, mem_search)

Agentes

El plugin usa 2 subagentes especializados que son delegados por qa-run durante la ejecucion. Cada uno tiene un rol acotado con tools restringidos al minimo necesario.

Agente Rol Modelo Tools maxTurns
qa-navigator Ejecuta flujos E2E en el browser: navega paginas, llena formularios, toma screenshots, verifica condiciones del DOM. Maneja los 4 tipos de autenticacion. sonnet Read, Bash (echo, curl), Playwright MCP (navigate, click, fill_form, type, press_key, snapshot, take_screenshot, evaluate, wait_for, hover, select_option, handle_dialog, console_messages, network_requests, tabs, navigate_back, file_upload, drag, run_code, resize) 30
qa-reporter Crea GitHub Issues estructurados para ACs que fallaron. Se delega cuando qa-run detecta un AC con status FAIL y necesita crear un issue con evidencia. sonnet Bash (gh), Read, Glob, Grep 15

Flujo de trabajo

El pipeline es secuencial en dos fases: configuracion y ejecucion. El usuario interactua con dos comandos simples:

  1. Configuracion (/qa-e2e:qa-wizard): El wizard identifica el Feature Spec (busca en Engram, .context/atl/, o GitHub), configura la URL del servidor de pruebas, elige la estrategia de autenticacion y extrae todos los ACs en formato Given/When/Then. Genera .context/qa-e2e/config.json.

  2. Verificacion del servidor: qa-run valida que el servidor responda antes de continuar. Si no responde, se detiene con mensaje claro.

  3. Autenticacion: qa-run delega al agente qa-navigator para autenticarse segun la estrategia configurada:

  4. form-login: navega al formulario, llena credenciales desde env vars, submit
  5. api-token: inyecta token en localStorage/headers
  6. manual-session: abre browser, pausa para login manual del usuario, captura cookies

  7. otp-interactive: llena formulario, pausa para que el usuario ingrese codigo 2FA, continua

  8. Ejecucion AC por AC: Para cada AC del Feature Spec, qa-run traduce Given/When/Then a pasos Playwright y delega a qa-navigator. El agente ejecuta el setup (Given), las acciones (When), y verifica las condiciones (Then). Toma screenshots antes y despues como evidencia.

  9. Reporte de fallos: Para cada AC con status FAIL, qa-run delega a qa-reporter para crear un GitHub Issue con: AC referenciado, escenario Given/When/Then, resultado observado, evidencia, pasos para reproducir y contexto tecnico.

  10. Reporte final: qa-run genera un reporte en .context/qa-e2e/results/ con resumen de cobertura (PASS/FAIL/ERROR/SKIP por AC) y lista de issues creados. Persiste el resultado en Engram.

Estrategias de autenticacion

Uno de los aspectos mas criticos del testing E2E es manejar la autenticacion correctamente. El plugin soporta 4 estrategias que cubren la mayoria de escenarios reales. Las credenciales nunca se guardan en archivos — siempre se leen de variables de entorno.

Estrategia Cuando usarla Env vars requeridas
form-login App con formulario web de login (usuario + contraseña) QA_E2E_USERNAME, QA_E2E_PASSWORD
api-token APIs o apps con auth por header (Bearer, API key) QA_E2E_API_TOKEN
manual-session Auth compleja: SSO, OAuth externo, CAPTCHA Ninguna (login manual)
otp-interactive Login con codigo 2FA, OTP por email/SMS QA_E2E_USERNAME, QA_E2E_PASSWORD
none App publica o paginas sin auth Ninguna

La referencia completa de cada estrategia (auto-deteccion de selectores, flujos Playwright, errores comunes) esta en skills/qa-wizard/references/auth-strategies.md.

Contratos de datos

Archivos producidos

El plugin genera archivos de configuracion y resultados que se almacenan en .context/qa-e2e/ (gitignored). Estos archivos conectan la fase de configuracion con la de ejecucion.

Archivo Productor Consumidor Descripcion
.context/qa-e2e/config.json qa-wizard qa-run Configuracion completa: feature, server, auth, ACs extraidos
.context/qa-e2e/results/{feature}-{timestamp}.json qa-run Externo Resultados crudos por AC con status, evidencia, timestamps
.context/qa-e2e/results/{feature}-report.md qa-run Externo Reporte legible con tabla de resultados y resumen

Archivos consumidos

Archivo Fuente Descripcion
.context/atl/{feature}/spec.md ATL / SDD-Wizards Feature Spec con ACs en formato Given/When/Then
GitHub milestone issues SDD-Wizards / SDD-Intake Feature Spec almacenado en GitHub Projects

Engram

El plugin usa Engram para persistir configuracion y resultados entre sesiones, siguiendo el patron de topic keys del equipo.

Topic key Writer Reader Contenido
qa-e2e/{feature}/config qa-wizard qa-run Resumen de configuracion de la sesion de testing
qa-e2e/{feature}/report qa-run Externo Resumen de resultados: ACs passed/failed, issues creados

GitHub

El plugin crea issues en GitHub con labels especificos para identificar fallos de E2E. Los labels se crean automaticamente con --force (idempotente).

Label Color Descripcion
qa-e2e #d93f0b Identifica issues creados por el plugin qa-e2e
ac-failure #e11d48 Criterio de aceptacion especifico que fallo
needs-fix #fbca04 Requiere correccion del equipo de desarrollo

Hooks

El plugin incluye un hook de seguridad que restringe los comandos Bash a una whitelist de operaciones seguras, previniendo ejecucion accidental de comandos destructivos durante el testing.

Hook Evento Script Que hace
block-destructive PreToolUse (matcher: Bash) hooks/block-destructive.sh Permite solo: echo, curl, gh, mkdir, ls, cat, date, printf, test. Bloquea todo lo demas con exit 2. Timeout: 10s.

Configuracion para proyectos

Para usar qa-e2e en un proyecto, agregar al CLAUDE.md del proyecto las variables de entorno y el flujo de testing. El template completo esta en examples/CLAUDE.md.

# Instalar Playwright MCP
claude mcp add playwright -- npx @anthropic-ai/mcp-playwright

# Configurar variables de auth
export QA_E2E_USERNAME="test@example.com"
export QA_E2E_PASSWORD="test-password"

# Lanzar Claude con el plugin
claude --plugin-dir ./plugins/qa-e2e

# Flujo de testing
/qa-e2e:qa-wizard mi-feature    # Paso 1: configurar
/qa-e2e:qa-run mi-feature       # Paso 2: ejecutar

Agregar a .gitignore: 

.context/qa-e2e/config.json

Limitaciones conocidas

  • No soporta CAPTCHA: Si el formulario de login tiene CAPTCHA, usar la estrategia manual-session como workaround.
  • Sesiones pueden expirar: En manual-session, si las pruebas tardan mucho la sesion capturada puede expirar. Re-ejecutar qa-wizard para recapturar.
  • Un browser a la vez: Playwright MCP ejecuta en un solo browser. Los ACs se prueban en secuencia, no en paralelo.
  • Screenshots como texto: Los screenshots se describen como texto en los issues de GitHub, no se adjuntan como imagenes (limitacion de gh issue create).
  • Requiere servidor corriendo: El servidor de pruebas debe estar levantado antes de ejecutar qa-run. El plugin no lo levanta automaticamente.