tuxedo-qa

Servidor MCP que permite ao Claude, Gemini e outros assistentes de IA compatíveis com MCP criar, rodar, autocorrigir e monitorar testes Playwright do seu app — com dashboard local, cofre de credenciais e página pública de status.

Landing page e documentação →

O que é

O tuxedo-qa expõe 16 ferramentas MCP que cobrem todo o ciclo de vida de uma suíte de testes sintéticos: escrever specs em linguagem natural, rodar sob demanda ou por agendamento, autocorrigir falhas, acessar ambientes de staging protegidos por headers, e expor os resultados numa página pública de status — tudo conduzido por uma conversa com seu assistente de IA, sem precisar de pipeline de CI.

Veja a referência completa das ferramentas e casos de uso na landing page.

Subagent do Claude Code

O instalador também registra o subagent tuxedo-qa-tester (globalmente, em ~/.claude/agents/) — ele já sabe as 16 ferramentas, as convenções de teste do projeto (usar o helper de credenciais em vez de senha fixa, brasil.ts pra CPF/CNPJ, human-loop.ts pra 2FA) e quando usar run_until_pass vs. corrigir manualmente. O Claude Code aciona ele sozinho quando a tarefa é sobre testes/QA; não precisa chamar por nome. (Só Claude Code por enquanto — o Gemini CLI não tem esse mecanismo de subagents ainda.)

Como começar

Instalador de um comando só — clona/atualiza, builda, e registra automaticamente no Claude Code e/ou Gemini CLI (o que você tiver instalado):

curl -fsSL https://raw.githubusercontent.com/jonathan-ponciano/sts-tools-mcp-tuxedo-qa/main/install.sh | bash

Instala em ~/tuxedo-qa por padrão (mude com TUXEDO_QA_DIR=/outro/caminho). Rodar de novo atualiza a instalação existente — seguro de repetir.

<details> <summary>Instalação manual</summary>

git clone https://github.com/jonathan-ponciano/sts-tools-mcp-tuxedo-qa.git
cd sts-tools-mcp-tuxedo-qa
npm install
npm run build

Registre como servidor MCP. No Claude Code (escopo user = disponível em todos os projetos):

claude mcp add tuxedoqa --scope user -- node "$(pwd)/dist/index.js"

No Gemini CLI (sem -- antes do comando — sintaxe diferente do Claude Code):

gemini mcp add tuxedoqa node "$(pwd)/dist/index.js" --scope user

</details>

Opcionalmente, inicie o dashboard local:

npm run dashboard
# → http://localhost:3131

Monitorando mais de um app/cliente

Uma instalação só do tuxedo-qa serve quantos projetos você quiser, cada um completamente isolado (testes, credenciais, schedule, histórico próprios), com um dashboard só pra ver e gerenciar todos eles juntos. A ideia:

• Cada projeto tem sua própria conexão MCP (o Claude/Gemini "conectado" naquele projeto específico só enxerga e mexe nos testes daquele projeto).
• O dashboard (npm run dashboard) não pertence a nenhum projeto — ele enxerga todos ao mesmo tempo, com um seletor pra trocar de contexto.
• O scheduler (monitoramento automático) roda dentro do dashboard e cuida de todos os projetos ao mesmo tempo, cada um no seu próprio horário.

1. Registrar um novo projeto

Rode o instalador de novo, passando um slug em TUXEDO_QA_PROJECT (letras, números, -/_). Ele reaproveita a mesma instalação (mesmo clone, mesmo node_modules) e só registra uma nova conexão MCP:

TUXEDO_QA_PROJECT=fretebras bash install.sh
# → registra o servidor MCP "tuxedoqa-fretebras"

TUXEDO_QA_PROJECT=xtagger bash install.sh
# → registra o servidor MCP "tuxedoqa-xtagger"

Repita pra cada projeto/cliente novo. Os dados de cada um ficam isolados em projects/<slug>/ dentro da instalação (~/tuxedo-qa/projects/fretebras/, ~/tuxedo-qa/projects/xtagger/, etc.) — testes, credenciais, schedule e histórico nunca se misturam entre projetos.

2. Usar cada projeto pelo Claude/Gemini

Depois de registrado, abra uma conversa e escolha a conexão MCP certa pra cada projeto (tuxedoqa-fretebras quando estiver falando sobre o Fretebras, tuxedoqa-xtagger pro xtagger). Cada uma só cria/roda/lê testes do seu próprio projeto — não tem como um misturar com o outro por acidente.

3. Ver tudo junto no dashboard

Suba o dashboard uma vez só (ele não precisa de TUXEDO_QA_PROJECT nenhum — enxerga todos sozinho):

npm run dashboard
# → http://localhost:3131

Na aba Monitor tem uma visão geral com todos os projetos (quantos testes, uptime, o que tá rodando agora). Clicar num projeto ali — ou usar o seletor no topo da página — troca o contexto do resto do dashboard (abas Testes, Credenciais, Proteção, Status Page) pra aquele projeto específico. É o mesmo dashboard, só muda o que ele mostra.

4. Monitoramento automático

O scheduler roda dentro do processo do dashboard e verifica todos os projetos a cada minuto — não importa qual está selecionado na tela no momento. Se fretebras tem um teste agendado a cada 1h e xtagger tem um a cada 6h, os dois rodam nos seus próprios horários, de forma independente, enquanto o dashboard estiver de pé.

Sem TUXEDO_QA_PROJECT

Se você só tem um projeto, não precisa mexer em nada disso — sem essa variável, tudo funciona no modo padrão (um projeto só, sem namespace), exatamente como antes.

Desenvolvimento

npm run dev         # roda o servidor MCP com tsx (sem build)
npm run dashboard    # dashboard em modo dev
npm test             # roda a suíte Playwright diretamente

Navegador headless vs. visível

Por padrão, todo teste roda headless — o Chromium abre em background, sem janela nenhuma na tela. Pra acompanhar visualmente o que o teste está fazendo (útil pra debugar um fluxo novo), basta passar a flag PWHEADED=1 antes do comando:

npx playwright test                # headless (padrão)
PWHEADED=1 npx playwright test     # abre o navegador visível
PWHEADED=1 npm run dev             # mesma flag funciona rodando via o servidor MCP

Isso vale pra qualquer execução — manual, via dashboard, ou disparada pelo Claude/Gemini com run_tests/run_until_pass/create_test — porque todas passam pelo mesmo runner (src/lib/playwright-runner.ts), que lê playwright.config.ts.

Licença

MIT