AIQUAA Playwright MCP Server

Gere testes BDD do Playwright, GitHub Actions e Azure Pipelines com rastreabilidade de regras de negócio, contexto focado do CodeGraph e memória persistente do Engram.

GitHubExperimente este MCPPatrocinado

Documentação

AIQUAA Playwright MCP Server

Converta requisitos em testes Playwright BDD rastreáveis, prontos para CI e conectados às regras de negócio que protegem.

AIQUAA Playwright MCP Server é um servidor Model Context Protocol para equipes de QA que precisam de mais do que código gerado: cenários Gherkin, automação Playwright, rastreabilidade por regra, pipelines reproduzíveis e cobertura auditável.

npm · última versão · relatar um problema

De uma história a evidência executável

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"]

O resultado não é um teste isolado. É uma cadeia de evidência:

cada cenário pode declarar qual regra valida;
cada execução preserva essa relação no reporter;
cada regra fica classificada como passed, failing, not_run ou uncovered;
GitHub Actions e Azure Pipelines recebem artefatos prontos para adaptar.

Por que usar

Necessidade	O que a AIQUAA oferece
Transformar histórias em BDD	Gera Gherkin revisável com fluxos positivos, validações e erros
Evitar seletores inventados	Registra sua procedência e deixa `TODO` explícitos quando falta contexto real
Testar regras, não apenas telas	Propaga `@rule:<ID>` até resultados e cobertura
Levar para CI	Gera configuração para GitHub Actions e Azure Pipelines
Gerenciar login e verificações externas	Usa `storageState`, segredos por ambiente e polling para e-mail, SMS, push ou APIs
Reduzir contexto repetido	Integra CodeGraph para código focado e Engram para memória persistente

Início rápido

1. Inicie o servidor

npx -y aiquaa-playwright-mcp-server

O servidor fica disponível em:

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

PORT e MCP_PATH são configuráveis.

2. Conecte seu cliente MCP

Para clientes compatíveis com Streamable HTTP, use esta definição como referência:

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

A localização exata do arquivo varia conforme o cliente. O servidor usa Streamable HTTP sem estado e cria um contexto isolado por solicitação.

3. Peça um fluxo 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.

O agente pode encadear qa_bdd → qa_mapear → qa_pruebas e devolver arquivos copiáveis.

As oito ferramentas

Os nomes são curtos, em espanhol e fáceis de descobrir:

Ferramenta	Resultado	Requer backend AIQUAA
`qa_bdd`	Features Gherkin a partir de texto ou `requirement_id`	Somente com IDs ou sugestão remota de regras
`qa_pruebas`	Steps, hooks, reporter, configuração, auth e pipelines	Somente com `feature_id`
`qa_reglas`	Regras paginadas com filtros	Sim
`qa_mapear`	Features etiquetados com `@rule:<ID>`	Não
`qa_cobertura`	Cobertura e estado por regra/feature	Evitável com snapshot offline
`qa_contexto`	Contexto estrutural focado via CodeGraph	Não
`qa_memoria`	Decisões e aprendizados recuperados do Engram	Não
`qa_recordar`	Memória curada e idempotente por `topic_key`	Não

Todos os inputs usam schemas Zod estritos. As ferramentas declaram suas annotations MCP de leitura, escrita, idempotência e acesso externo.

O que gera

Dependendo das opções selecionadas, qa_pruebas pode retornar:

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

Além disso, o pacote exporta extensões reutilizáveis:

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

O projeto gerado usa as APIs públicas de playwright-bdd e Playwright. Não modifica internals do runner.

Exemplo: feature para Playwright

Invocação 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"
}

No projeto de testes:

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

O reporter escreve test-results/aiquaa-rule-results.json, compatível com qa_cobertura.

Seletores que não vendem fumaça

O gerador distingue a origem real de cada locator:

provided_dom: DOM renderizado inspecionado;
provided_component: componente React, Vue, Angular ou outro código real;
provided_test_ids: inventário confirmado de data-testid;
estimated: inferido apenas a partir do Gherkin.

Se faltar informação para implementar uma ação ou assertion confiável, gera um TODO que falha explicitamente. Não produz falsos positivos verificando apenas que a página existe.

Segurança desde o design

Não inclui credenciais fallback em código gerado.
auth.setup.ts exige segredos e usa Playwright storageState.
SMS, e-mail, push e estados externos são consultados por meio de variáveis de ambiente.
O Bearer token recebido pelo MCP é usado apenas para essa solicitação.
CodeGraph só pode ler caminhos sob CODEGRAPH_ALLOWED_ROOTS.
Engram fica limitado a memória com escopo de projeto.

O passthrough de Bearer protege as chamadas à AIQUAA, mas não substitui a autenticação do próprio endpoint MCP. Se você o expor na Internet, proteja-o com um gateway ou reverse proxy.

Uso offline e conectado

A maior parte do fluxo funciona sem backend:

qa_bdd aceita texto direto;
qa_pruebas aceita Gherkin direto;
qa_mapear é completamente local;
qa_cobertura aceita um snapshot de regras.

Para resolver IDs e consultar regras, configure:

Variável	Uso
`AIQUAA_API_BASE_URL`	URL do backend AIQUAA
`AIQUAA_ACCESS_TOKEN`	Bearer token de desenvolvimento; em produção, prefira o header por solicitação
`PORT`	Porta HTTP, default `3000`
`MCP_PATH`	Rota MCP, default `/mcp`

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

As rotas atuais do cliente AIQUAA estão centralizadas em src/constants.ts e devem ser confirmadas contra o OpenAPI real:

Operação	Rota assumida
Regras	`GET /projects/:projectId/business-rules`
Requisito	`GET /projects/:projectId/requirements/:requirementId`
Feature	`GET /features/:featureId`

Contexto eficiente com CodeGraph

CodeGraph constrói contexto estrutural focado antes de gerar testes. É especialmente útil quando o servidor compartilha filesystem com o repositório em teste.

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

export CODEGRAPH_BIN=codegraph
export CODEGRAPH_ALLOWED_ROOTS=/workspace/projects

Use qa_contexto para localizar rotas, componentes, labels e test IDs; depois passe o resultado como app_context para qa_pruebas. No Windows, separe múltiplas raízes permitidas com ;; no Linux/macOS, com :.

Memória persistente com Engram

Engram preserva decisões úteis entre sessões sem converter cada tool call em memória.

export ENGRAM_BIN=engram
export ENGRAM_PROJECT_PREFIX=aiquaa-

qa_memoria busca apenas dentro do projeto indicado.
qa_recordar exige um topic_key estável para atualizar em 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.

Em contêineres, monte o diretório de dados do Engram como volume persistente. Não publique sua base como artifact: pode conter contexto sensível.

CI/CD incluído

O repositório valida cada alteração por meio de .github/workflows/ci.yml. Para projetos consumidores, inclui:

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

Ambos exemplos executam bddgen, rodam Playwright, publicam JUnit e preservam relatórios como artifacts. As releases npm são publicadas via Trusted Publishing/OIDC, sem tokens permanentes.

Migração a partir da v0.1.x

A versão 0.2.0 reduziu os nomes públicos para economizar contexto. É uma mudança incompatível intencional; não são duplicados 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`

Escopo deliberado

Este MCP gera e conecta artefatos. Não:

abre navegadores nem executa testes dentro do servidor;
faz OCR de PDFs;
adivinha que um seletor estimado foi validado;
substitui a revisão humana do Gherkin gerado;
conta como uncovered uma regra que não foi incluída na AIQUAA ou no snapshot.

Para PDFs, extraia primeiro o texto com uma ferramenta especializada e envie requirement_source: "extracted_from_pdf"; o servidor aplica guardrails contra OCR evidentemente quebrado.

Desenvolvimento

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

O projeto usa TypeScript estrito, 9 testes automatizados e 13 avaliações MCP. Os YAML gerados e os exemplos estáticos são validados automaticamente.

Licença

MIT. playwright-bdd mantém licença MIT e Playwright licença Apache-2.0.

Se este projeto ajuda você a converter requisitos em evidência de qualidade, deixe uma ⭐ e compartilhe qual integração você gostaria de ver a seguir.