QA Agent CLI

CLI publicada como @rjlaguardia/qa-agent para ajudar o QA a:

1. entender o sistema a partir do codigo e da documentacao;
2. gerar analise estruturada do projeto;
3. gerar cenarios Gherkin;
4. criar uma base Playwright com page objects e specs iniciais.

Experiencia recomendada para o QA

Depois de instalar no projeto alvo:

npx @rjlaguardia/qa-agent init --repo .

Isso prepara o projeto e cria um arquivo importante:

• docs/qa-agent.md

O QA deve abrir esse arquivo e colar:

• resumo funcional do produto
• fluxos criticos
• regras de negocio
• perfis e permissoes
• riscos conhecidos
• qualquer documentacao funcional relevante

Esse arquivo entra como contexto adicional porque a ferramenta le a pasta docs/ por padrao.

Projetos grandes

Por padrao, o QA Agent agora tenta detectar automaticamente um escopo mais enxuto para a analise, priorizando pastas como:

• src
• app
• lib
• frontend
• backend
• client
• server
• web
• api
• apps/*/src
• packages/*/src
• services/*/src

Tambem ignora por padrao pastas pesadas como:

• node_modules
• android
• ios
• build
• .next
• .turbo
• coverage

Antes de rodar a analise real, use:

npm run qa:preview

e revise em:

• qa-output/reports/analysis-manifest.json

Se o escopo automatico nao ficar bom, ajuste includeDirectories e docsPaths no qa-assistant.config.json.

Fluxo mais simples

No projeto alvo, depois do init, o QA pode usar:

npm run qa:secret
npm run qa:preview
npm run qa:analyze
npm run qa:gherkin
npm run qa:playwright

O que cada passo faz

• qa:secret: grava a OPENAI_API_KEY no .env
• qa:preview: mostra o manifesto dos arquivos que podem entrar na analise
• qa:preview: tambem mostra o escopo detectado automaticamente para projeto grande
• qa:analyze: gera a analise estruturada real do sistema
• qa:gherkin: transforma a analise em cenarios Gherkin
• qa:playwright: gera page objects e specs iniciais

Comandos principais

qa-agent init --repo .
qa-agent docs
qa-agent setup-secret --repo .
qa-agent analyze-project --repo . --dry-run
qa-agent analyze-project --repo . --allow-ai-read
qa-agent generate-gherkin --repo .
qa-agent bootstrap-playwright --repo .
qa-agent generate-playwright --repo .
qa-agent run --repo . --allow-ai-read

Scripts adicionados ao projeto alvo

Quando voce roda setup-target ou init, o CLI tenta adicionar estes scripts ao package.json do repositorio alvo:

• qa:init
• qa:docs
• qa:secret
• qa:setup
• qa:preview
• qa:analyze:preview
• qa:analyze
• qa:gherkin
• qa:playwright:bootstrap
• qa:playwright
• qa:run

Guardrails de seguranca

• analyze-project e run nao enviam codigo para a IA sem --allow-ai-read
• --dry-run gera um manifesto auditavel antes de qualquer envio
• arquivos sensiveis como .env, .npmrc, secrets, credentials e chaves privadas sao bloqueados por padrao
• arquivos grandes demais ficam fora da analise
• a CLI grava um log com os arquivos efetivamente lidos pela IA

Saidas geradas

• docs/qa-agent.md
• qa-output/reports/analysis-manifest.json
• qa-output/reports/project-analysis.json
• qa-output/reports/project-analysis-summary.json
• qa-output/reports/ai-read-log.json
• qa-output/reports/test-plan.json
• qa-output/features/*.feature
• tests/pages/*
• tests/generated/*

Publicacao publica

npm run build
npm run pack:dry-run
npm run publish:public