# Agentic QA > Executa suíte autônoma de QA/E2E com emulação de personas, navegação de browser, discovery de bugs, triagem de issues e correções em paralelo. Use para scaffold .agentic-qa, emulação de usuários, testes de navegação, triagem ou correções autônomas de QA. - Skill: `paulohfs/agentic-qa` (Agent Skill) - Install (CLI): `npx skillmds@latest add paulohfs/agentic-qa` - Raw SKILL.md: https://api.skillmd.com/api/skills/paulohfs/agentic-qa/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: PauloHFS (https://skillmd.com/u/paulohfs) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/paulohfs/agentic-qa --- # Agentic QA & E2E Testing Skill para scaffold de testes autônomos de QA, emulação de personas de usuário via browser, discovery/reporte de bugs e triagem com correções paralelas. > **Regra Anti-Atalho**: NUNCA substitua a execução da matriz de personas por testes unitários/estáticos como `npm run test` ou `vitest`. Esta skill EXIGE navegação e emulação real de browser por persona contra cada story. --- ```text .agentic-qa/ ├── framework.md # Regras globais de teste, asserções, seletores e logging ├── latest-run.json # Arquivo temporário de estado da matriz (gerado na execução) ├── product/ # Documentação de contexto e regras de negócio │ └── .md # Ex: search.md, checkout.md, auth.md ├── stories/ # Casos de uso e roteiros de navegação declarativos │ └── .md # Ex: search.md, checkout-flow.md └── personas/ # Perfis de emulação estruturados em YAML └── .yaml # Ex: default.yaml, dona_maria.yaml ``` ### Scaffold e Inicialização Ao preparar um projeto para Agentic QA: 1. Verifique se `.agentic-qa/` existe no repositório. 2. Caso ausente, crie o diretório e os arquivos base: `framework.md`, `product/default.md`, `stories/smoke.md` e `personas/default.yaml`. 3. **Configuração de `.gitignore`**: Adicione as entradas temporárias de QA ao `.gitignore` do repositório: ```gitignore # Agentic QA temporary state & artifacts .agentic-qa/latest-run.json .agentic-qa/artifacts/ .agentic-qa/*.log ``` 4. **Critério de Conclusão**: O diretório `.agentic-qa/` foi instanciado com os 4 arquivos base e o `.gitignore` atualizado protegendo o estado temporário. --- ## 2. Pre-check & Validação de Ambiente Antes de iniciar a matriz de emulação, valide e garanta a prontidão de todos os serviços necessários: 1. **Inspeção de Infraestrutura e Serviços**: * **Containers / Docker / OrbStack**: Se o projeto depende de banco de dados ou microserviços em container, verifique a execução (`docker ps` ou similar). Se inativos, suba os serviços (`docker compose up -d`). * **Supabase / BaaS**: Se utilizado Supabase local ou outro BaaS, valide o status (`supabase status`). Suba se necessário (`supabase start`). * **Frontend / Server App**: Verifique se a aplicação web está ativa na porta/URL alvo da story (ex: `http://localhost:3000` ou `5173`). Se inativa, inicie o dev server via `hub` (`op: "start"`, ex: `npm run dev`) e aguarde prontidão no log/porta. * **Backend / API**: Se houver servidor API em porta distinta, verifique conectividade HTTP antes de prosseguir. * **Mobile / Emulador**: Se a persona especificar `device.type: mobile` com app nativo, valide se o emulador/simulador (Android Emulator / iOS Simulator / Metro) está acessível. 2. **Diagnóstico e Bloqueio de Pré-requisitos (Pre-check Failure)**: * Se algum serviço, banco ou servidor web não estiver responsivo e não puder ser iniciado automaticamente: * O agente DEVE **interromper a execução imediatamente** e reportar explicitamente a rota/porta inacessível junto com a instrução de comando para o usuário. * Exemplo de mensagem: `❌ Pre-check Agentic QA: O serviço [Frontend/API] em http://localhost:8000 não respondeu. Execute 'npm run dev' (ou o comando equivalente) no terminal e re-execute a suíte.` 3. **Critério de Conclusão do Pre-check**: Todos os endpoints, bancos e serviços exigidos pelas stories estão ativos e respondendo a requisições HTTP < 500, ou o agente exibiu o aviso de bloqueio indicando o comando exato necessário. --- ## 3. Schemas e Formatos Declarativos * **Markdown (`.md`)**: Documentação de produto (`product/`), roteiros de navegação (`stories/`) e regras de execução (`framework.md`). * **YAML (`.yaml`)**: Estado, contexto técnico e limites comportamentais da persona (`personas/`). Mapeia diretamente para chamadas de ferramentas de browser. ### Schema de Persona (`personas/.yaml`) ```yaml persona: # Identity / Context name: "Dona Maria" bio: "Usuária não-técnica, navegação cautelosa." disability: null # null | color_blind_deuteranopia | color_blind_protanopia | low_vision # Geo / Region locale: language: "pt-BR" region: "BR" currency: "BRL" date_format: "DD/MM/YYYY" timezone: "America/Sao_Paulo" # Technical Environment device: type: "mobile" # mobile | tablet | desktop model: "Samsung Galaxy A32" os: "Android 12" network: profile: "3G" # offline | 2G | 3G | 4G | broadband download_mbps: 1.5 upload_mbps: 0.5 latency_ms: 150 viewport: width: 360 height: 800 # Navigation Guidance network_tolerance: max_load_ms: 8000 on_timeout: "retry_once" # retry_once | fail | wait max_retries: 1 # Behavioral Limits patience: retries: 2 # Tentativas antes de desistir do fluxo timeout: 6000 # Tempo máximo aceito de espera por recursos (ms) ``` ### Schema de Roteiro (`stories/.md`) ```markdown # Story: Target: Prerequisites: ## Steps 1. Navigate to `` 2. Wait for `` 3. Action: `` on `` value `` 4. Assert: `` ``` ### Schema de Framework (`framework.md`) ```markdown # Framework Rules - Global Timeout: 10000ms - Screenshot on Failure: true - Console Error Threshold: ignore non-fatal warnings; report unhandled exceptions & 5xx HTTP responses - Deduplication: Check existing open issues before reporting new bugs ``` ### Schema de Estado de Execução (`latest-run.json`) ```json { "started_at": "2026-08-22T10:00:00Z", "status": "in_progress", "matrix": [ { "persona": "dona_maria.yaml", "story": "checkout-flow.md", "status": "passed", // "pending" | "passed" | "failed" "duration_ms": 4200, "errors": [], "artifacts": { "screenshots": ["artifact://screenshot-1.png"], "console_logs": [] } } ] } ``` --- ## 4. Pipeline de Execução ### Fase 1: Matriz Combinatória de Emulação ($N \text{ Personas} \times M \text{ Stories}$) O agente DEVE iterar de forma explícita sobre a matriz de execução: $$\text{Execuções} = \{ (P, S) \mid P \in \text{Personas}, S \in \text{Stories} \}$$ 1. **Inicialização da Matriz e Isolamento de Sessão**: * **Criar/Carregar Estado**: Antes da primeira execução, criar ou carregar `.agentic-qa/latest-run.json` populando a lista de combinações $(P, S)$ com status `pending`. * **Isolamento Estrito de Sessão**: Ao trocar de persona, **limpar obrigatoriamente** todos os cookies, `localStorage`, `sessionStorage` e dados de navegação no browser (`browser` / `xd://browser`) para evitar contaminação de contexto entre perfis. 2. **Loop Principal de Emulação**: * Para cada persona $P$ em `personas/*.yaml`: * Para cada story $S$ em `stories/*.md`: a. Se a célula $(P, S)$ em `latest-run.json` já estiver `passed`, pular (garantindo retomada resiliente). b. **Configurar Browser**: Limpar sessão anterior e aplicar `viewport`, `user-agent`, throttling de rede e `locale` da persona $P$. c. **Executar Roteiro**: Ler `product/.md` e seguir os passos de $S$ aplicando os limites de paciência e timeouts de $P$. d. **Registrar no Estado**: Atualizar a célula em `latest-run.json` com `status: "passed"` ou `"failed"`, incluindo duração e artefatos/screenshots. 3. **Registro de Falhas (Issue Creation)**: * Registrar falha ao detectar: erros de console não-tratados, status HTTP 5xx, falhas de asserção visual/DOM ou timeouts estourados. * **Deduplicação**: Buscar em issues abertas (`issue://` ou CLI git) antes de registrar. * **Abrir Issue**: Registrar com o template: * **Título**: `[QA Persona: ] ` * **Contexto**: Persona utilizada, Device, Rede, Viewport. * **URL / Rota**: Link da tela afetada. * **Step-by-Step de Reprodução**: Passos determinísticos para replicar o erro. * **Comportamento Esperado vs. Obtido**: Logs de erro, status code ou prints. * **Critério de Conclusão**: Todas as combinações $(P, S)$ foram executadas em browser real; falhas foram registradas em issues deduplicadas. --- ### Fase 2: Triagem e Resolução Paralela (Engenharia & Review) 1. **Análise de Causa Raiz**: * Varrer issues abertas de QA. * Cruzar o step-by-step com a codebase e identificar arquivo/linha causadores. 2. **Correção Paralela (Subagentes `task`)**: * Disparar subagentes `task` em paralelo para cada issue analisada. * Cada subagente deve: * Reproduzir o erro em ambiente isolado. * Aplicar a correção mínima necessária mantendo a suíte de testes verde. * Re-executar o roteiro de QA com a persona afetada confirmando a resolução verde. * Abrir Pull Request ou commit referenciando a issue (`Fixes #`). * Se a correção não for viável ou for comportamento pretendido: comentar justificativa técnica `wontfix`. 3. **Auditoria e Pré-Aprovação**: * Analisar os diffs das PRs geradas. * Validar ausência de breaking changes, regressões e aderência às regras do repositório. * **Critério de Conclusão**: Todas as issues abertas possuem PR verificado verde ou justificativa `wontfix` registrada.