AIQUAA Playwright MCP Server

Convertí requisitos en pruebas Playwright BDD trazables, listas para CI y conectadas con las reglas de negocio que protegen.

AIQUAA Playwright MCP Server es un servidor Model Context Protocol para equipos de QA que necesitan algo más que código generado: escenarios Gherkin, automatización Playwright, trazabilidad por regla, pipelines reproducibles y cobertura auditable.

npm · última release · reportar un problema

De una historia a evidencia ejecutable

flowchart LR
    A["Requisito o historia"] --> B["qa_bdd"]
    B --> C["Escenarios Gherkin"]
    C --> D["qa_mapear"]
    D --> E["Tags @rule"]
    E --> F["qa_pruebas"]
    F --> G["Playwright + CI"]
    G --> H["Resultados"]
    H --> I["qa_cobertura"]
    I --> J["Cobertura por regla"]

El resultado no es un test aislado. Es una cadena de evidencia:

• cada escenario puede declarar qué regla valida;
• cada ejecución conserva esa relación en el reporter;
• cada regla queda clasificada como passed, failing, not_run o uncovered;
• GitHub Actions y Azure Pipelines reciben artefactos listos para adaptar.

Por qué usarlo

| Necesidad | Qué aporta AIQUAA | |---|---| | Pasar historias a BDD | Genera Gherkin revisable con flujos positivos, validaciones y errores | | Evitar selectores inventados | Registra su procedencia y deja TODO explícitos cuando falta contexto real | | Probar reglas, no solo pantallas | Propaga @rule:<ID> hasta resultados y cobertura | | Llevarlo a CI | Genera configuración para GitHub Actions y Azure Pipelines | | Manejar login y verificaciones externas | Usa storageState, secretos por entorno y polling para email, SMS, push o APIs | | Reducir contexto repetido | Integra CodeGraph para código enfocado y Engram para memoria persistente |

Quick start

1. Iniciá el servidor

npx -y aiquaa-playwright-mcp-server

El servidor queda disponible en:

• MCP: http://localhost:3000/mcp
• Health check: http://localhost:3000/health

PORT y MCP_PATH son configurables.

2. Conectá tu cliente MCP

Para clientes compatibles con Streamable HTTP, usá esta definición como referencia:

{
  "mcpServers": {
    "aiquaa-qa": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

La ubicación exacta del archivo cambia según el cliente. El servidor usa Streamable HTTP sin estado y crea un contexto aislado por solicitud.

3. Pedile un flujo completo

Generá escenarios BDD para recuperación de contraseña, mapealos a
RN-014 y RN-015, y prepará los tests Playwright para GitHub Actions.
No ejecutes el navegador.

El agente puede encadenar qa_bdd → qa_mapear → qa_pruebas y devolverte archivos copiables.

Las ocho tools

Los nombres son breves, en español y fáciles de descubrir:

| Tool | Resultado | Requiere backend AIQUAA | |---|---|---| | qa_bdd | Features Gherkin desde texto o requirement_id | Solo con IDs o sugerencia remota de reglas | | qa_pruebas | Steps, hooks, reporter, configuración, auth y pipelines | Solo con feature_id | | qa_reglas | Reglas paginadas con filtros | Sí | | qa_mapear | Features etiquetados con @rule:<ID> | No | | qa_cobertura | Cobertura y estado por regla/feature | Evitable con snapshot offline | | qa_contexto | Contexto estructural enfocado mediante CodeGraph | No | | qa_memoria | Decisiones y aprendizajes recuperados desde Engram | No | | qa_recordar | Memoria curada e idempotente por topic_key | No |

Todos los inputs usan schemas Zod estrictos. Las tools declaran sus annotations MCP de lectura, escritura, idempotencia y acceso externo.

Qué genera

Según las opciones seleccionadas, qa_pruebas puede devolver:

features/
├── steps/*.steps.ts
└── support/
    ├── auth.setup.ts
    ├── external-validation.ts
    └── rule-hooks.ts
playwright.config.ts
.github/workflows/playwright.yml
azure-pipelines.playwright.yml

Además, el paquete exporta extensiones reutilizables:

import AiquaaRuleReporter from "aiquaa-playwright-mcp-server/rule-reporter";
import { ruleIdsFromTags } from "aiquaa-playwright-mcp-server/rule-tags";

El proyecto generado usa las APIs públicas de playwright-bdd y Playwright. No modifica internals del runner.

Ejemplo: feature a Playwright

Invocación de qa_pruebas:

{
  "feature_content": "Feature: Login\nScenario: Acceso válido\nGiven el usuario está en login\nWhen hace clic en \"Ingresar\"\nThen ve \"Inicio\"",
  "base_url": "https://staging.example.com",
  "app_context": "El formulario usa labels Email y Contraseña.",
  "selector_source": "provided_component",
  "auth": {
    "login_path": "/login",
    "username_label": "Email",
    "password_label": "Contraseña",
    "submit_name": "Ingresar",
    "success_url_pattern": "dashboard",
    "username_env": "TEST_USER",
    "password_env": "TEST_PASSWORD"
  },
  "browsers": ["chromium"],
  "ci_targets": ["github_actions", "azure_pipelines"],
  "response_format": "json"
}

En el proyecto de pruebas:

npm install -D @playwright/test playwright-bdd aiquaa-playwright-mcp-server
npx bddgen
npx playwright test

El reporter escribe test-results/aiquaa-rule-results.json, compatible con qa_cobertura.

Selectores que no venden humo

El generador distingue el origen real de cada locator:

• provided_dom: DOM renderizado inspeccionado;
• provided_component: componente React, Vue, Angular u otro código real;
• provided_test_ids: inventario confirmado de data-testid;
• estimated: inferido solo desde Gherkin.

Si falta información para implementar una acción o assertion confiable, genera un TODO que falla explícitamente. No produce falsos positivos comprobando únicamente que la página existe.

Seguridad desde el diseño

• No incluye credenciales fallback en código generado.
• auth.setup.ts exige secretos y usa Playwright storageState.
• SMS, email, push y estados externos se consultan mediante variables de entorno.
• El Bearer token recibido por el MCP se usa únicamente para esa solicitud.
• CodeGraph solo puede leer rutas bajo CODEGRAPH_ALLOWED_ROOTS.
• Engram queda limitado a memoria con scope de proyecto.

El passthrough de Bearer protege las llamadas a AIQUAA, pero no reemplaza la autenticación del propio endpoint MCP. Si lo exponés en Internet, protegelo con un gateway o reverse proxy.

Uso offline y conectado

La mayoría del flujo funciona sin backend:

• qa_bdd acepta texto directo;
• qa_pruebas acepta Gherkin directo;
• qa_mapear es completamente local;
• qa_cobertura acepta un snapshot de reglas.

Para resolver IDs y consultar reglas configurá:

| Variable | Uso | |---|---| | AIQUAA_API_BASE_URL | URL del backend AIQUAA | | AIQUAA_ACCESS_TOKEN | Bearer token de desarrollo; en producción preferí el header por solicitud | | PORT | Puerto HTTP, default 3000 | | MCP_PATH | Ruta MCP, default /mcp |

$env:AIQUAA_API_BASE_URL="https://api.example.aiquaa.com"
$env:AIQUAA_ACCESS_TOKEN="<token-local>"
npx aiquaa-playwright-mcp-server

Las rutas actuales del cliente AIQUAA están centralizadas en src/constants.ts y deben confirmarse contra el OpenAPI real:

| Operación | Ruta asumida | |---|---| | Reglas | GET /projects/:projectId/business-rules | | Requerimiento | GET /projects/:projectId/requirements/:requirementId | | Feature | GET /features/:featureId |

Contexto eficiente con CodeGraph

CodeGraph construye contexto estructural enfocado antes de generar tests. Resulta especialmente útil cuando el servidor comparte filesystem con el repositorio bajo prueba.

npm install -g @colbymchenry/codegraph
cd /workspace/projects/checkout
codegraph init -i

export CODEGRAPH_BIN=codegraph
export CODEGRAPH_ALLOWED_ROOTS=/workspace/projects

Usá qa_contexto para localizar rutas, componentes, labels y test IDs; luego pasá el resultado como app_context a qa_pruebas. En Windows, separá múltiples raíces permitidas con ;; en Linux/macOS, con :.

Memoria persistente con Engram

Engram conserva decisiones útiles entre sesiones sin convertir cada tool call en memoria.

export ENGRAM_BIN=engram
export ENGRAM_PROJECT_PREFIX=aiquaa-

• qa_memoria busca solo dentro del proyecto indicado.
• qa_recordar exige un topic_key estable para actualizar en vez de duplicar.

Formato recomendado:

What: se eligió getByRole para acciones primarias.
Why: conserva semántica accesible y evita CSS frágil.
Where: features/steps/login.steps.ts.
Learned: data-testid queda para controles sin nombre accesible estable.

En contenedores, montá el directorio de datos de Engram como volumen persistente. No publiques su base como artifact: puede contener contexto sensible.

CI/CD incluido

El repositorio valida cada cambio mediante .github/workflows/ci.yml. Para proyectos consumidores incluye:

• examples/ci/github-actions-playwright.yml
• examples/ci/azure-pipelines-playwright.yml

Ambos ejemplos ejecutan bddgen, corren Playwright, publican JUnit y conservan reportes como artifacts. Las releases npm se publican mediante Trusted Publishing/OIDC, sin tokens permanentes.

Migración desde v0.1.x

La versión 0.2.0 redujo los nombres públicos para ahorrar contexto. Es un cambio incompatible intencional; no se duplican aliases.

| v0.1.x | v0.2.x | |---|---| | aiquaa_generate_bdd_scenarios | qa_bdd | | aiquaa_generate_playwright_tests | qa_pruebas | | aiquaa_list_business_rules | qa_reglas | | aiquaa_map_scenarios_to_rules | qa_mapear | | aiquaa_generate_coverage_report | qa_cobertura | | aiquaa_get_code_context | qa_contexto | | aiquaa_search_project_memory | qa_memoria | | aiquaa_save_project_memory | qa_recordar |

Alcance deliberado

Este MCP genera y conecta artefactos. No:

• abre navegadores ni ejecuta pruebas dentro del servidor;
• hace OCR de PDFs;
• adivina que un selector estimado fue validado;
• reemplaza la revisión humana del Gherkin generado;
• cuenta como uncovered una regla que no fue incluida en AIQUAA o en el snapshot.

Para PDFs, extraé primero el texto con una herramienta especializada y enviá requirement_source: "extracted_from_pdf"; el servidor aplica guardrails contra OCR evidentemente roto.

Desarrollo

git clone https://github.com/stevenayal/aiquaa-playwright-mcp-server.git
cd aiquaa-playwright-mcp-server
npm ci
npm test

El proyecto usa TypeScript estricto, 9 pruebas automatizadas y 13 evaluaciones MCP. Los YAML generados y los ejemplos estáticos se validan automáticamente.

Licencia

MIT. playwright-bdd mantiene licencia MIT y Playwright licencia Apache-2.0.

Si este proyecto te ayuda a convertir requisitos en evidencia de calidad, dejá una ⭐ y compartí qué integración te gustaría ver después.