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.

.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
│   └── <feature>.md       # Ex: search.md, checkout.md, auth.md
├── stories/               # Casos de uso e roteiros de navegação declarativos
│   └── <workflow>.md      # Ex: search.md, checkout-flow.md
└── personas/              # Perfis de emulação estruturados em YAML
    └── <persona>.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:

   # 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/<nome>.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/<workflow>.md)

# Story: <Nome do Roteiro>
Target: <URL relativa ou rota base>
Prerequisites: <Estado prévio ou autenticação necessária>

## Steps
1. Navigate to `<rota>`
2. Wait for `<seletor ou texto>`
3. Action: `<click|type|select>` on `<seletor>` value `<valor>`
4. Assert: `<condição esperada em tela ou resposta HTTP>`

Schema de Framework (framework.md)

# 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)

{
  "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/<feature>.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: <Nome>] <Descrição concisa da falha>
     • 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 #<id>).
     • 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.