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.

Related MCP server: AutoDev MCP

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="<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:

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.