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

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:

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á:

$env:AIQUAA_API_BASE_URL="https://api.example.aiquaa.com"
$env:AIQUAA_ACCESS_TOKEN=""
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:

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.

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.