Triagem de Falhas — Cypress Core

Protocolo de como uma falha de teste é investigada e resolvida neste projeto. A captura do fato bruto é automática (ver Passo 0) — a investigação continua manual/com o Claude, é o "modo manual" da automação com IA descrito na conversa de 20/08/2026: processo formal em vez de correção no chute, mas sem gatilho automático pra investigar sozinho.

Passo 0 — Onde achar falha pra investigar

Duas formas de uma falha chegar até aqui:

• Alguém traz na hora (cola o erro numa conversa, ou pede pra investigar algo que acabou de acontecer).
• Captura automática: todo teste que falha, em qualquer execução (cypress open ou cypress run, local ou de qualquer máquina), já vira uma entrada em docs/falhas-pendentes.md sozinho — via um afterEach global (cypress/support/e2e.js) + uma task do Cypress (cypress.config.js) que grava o fato bruto (spec, teste, mensagem de erro, quando, pasta do screenshot). Isso resolve o problema de "rodei sozinho e o erro se perdeu" — mas só captura o fato, não investiga a causa: continua precisando de alguém (ou de mim, numa sessão) passar pelos passos abaixo.

De vez em quando (ou sempre que for mexer no projeto), vale abrir docs/falhas-pendentes.md e ver se tem algo acumulado esperando triagem.

Ponto cego confirmado (31/08/2026): a captura automática só cobre falha de teste (it()) — falha de hook (before/beforeEach de nível de suíte, ex.: cy.login() travando dentro do before() raiz) não passa pelo afterEach global, então nunca vira entrada em falhas-pendentes.md. Esse tipo de falha só aparece se alguém trouxer o print/log na hora, ou olhando o relatório/terminal direto — vale lembrar disso antes de concluir "não tem nada pendente" só porque o arquivo está vazio.

Passo 1 — Investigar de verdade antes de corrigir

Nunca alterar um seletor, endpoint ou payload só por suposição. Confirmar a causa real:

• Se for tela: abrir o app de verdade (mesma sessão logada) e inspecionar o DOM real — read_page/javascript_exec no elemento que falhou, não confiar em como ele "parece" no print.
• Se for API: consultar a collection real no Postman (MCP) ou reproduzir a chamada, em vez de adivinhar o formato do payload/resposta.

Precedente: metade dos bugs consertados neste projeto não eram o que pareciam à primeira vista — o botão "Detalhes" nunca foi um <button> (era um MUI Chip), o scroll que "não funcionava" na verdade estava sendo desfeito pelo próprio Cypress, o guid da resposta de "Gerar Boleto" era provisório. Nenhum desses foi resolvido no chute — só inspecionando de verdade.

Passo 2 — Classificar a falha

Cuidado ao rodar filtrado (--env grep/grepTags, it.only)

before() roda sempre, mesmo quando nenhum it() de dentro bate com o filtro — achado real em 26/08/2026 (ver docs/historico-de-falhas.md). O @cypress/grep só marca os it()s que não batem como pendentes; não pula o before() do describe. Um spec com efeito colateral real no before() (cria Administradora/Condomínio) ainda cria dado de verdade mesmo rodando só por tag, mesmo que o describe inteiro esteja fora do filtro pedido — isso já aconteceu de verdade rodando grepTags=@boleto+@regressao sem --spec, que tocou before() de specs fora desse filtro. Mitigação: sempre combinar grepTags/grep com --spec restringindo os arquivos, ou usar grepFilterSpecs=true (pré-filtra o arquivo inteiro antes de carregar) — ver README, seção "Rodar por tag".

Passo 3 — Corrigir e documentar

• Corrigir só o necessário pra causa identificada — não "aproveitar" pra mexer em outra coisa.
• Se a causa revelou uma regra de negócio nova (campo obrigatório, status, dependência entre telas, limite/bloqueio): registrar em docs/regras-de-negocio.md, na seção do módulo correspondente, mesmo que o teste em si já tenha sido corrigido. O código do teste documenta "como testar"; esse arquivo documenta "o que o produto faz" — são coisas diferentes, as duas precisam ficar atualizadas.
• Sempre registrar uma entrada em docs/historico-de-falhas.md (mais nova no topo) — mesmo quando a categoria for instabilidade/ambiente e nenhum código tenha sido alterado. É o que permite enxergar padrão ao longo do tempo (ex.: mesmo timeout se repetindo toda semana).
• Se a falha veio de docs/falhas-pendentes.md: apagar a entrada correspondente de lá depois de registrar em historico-de-falhas.md — exceto quando a causa confirmada é um erro real que precisa de correção no Core (bug de produto, não instabilidade/ambiente) e ainda não existe número de demanda aberto no Azure DevOps pra ele. Nesse caso a entrada fica de propósito na fila — é o jeito de não perder de vista "isso é bug confirmado, falta só abrir o ticket". Ela some da fila sozinha assim que alguém publica Story/Bug/Task (ou comenta num item já existente) por ela na aba Azure DevOps do painel (removerFalhaPendenteSeExistir() em painel-local/server.js, dispara automaticamente ao publicar com sucesso) — não precisa apagar na mão nesse fluxo. Recorrência de um achado que já tem número de demanda (ver a tabela "Work Items do Azure DevOps vinculados" em historico-de-falhas.md, ou o badge "🔗 Já reportado" no painel) continua saindo da fila na triagem manual de sempre, mesmo sem publicar nada de novo — o rastreio dela já está garantido em outro lugar.
• Reportar de volta, sempre com 3 partes: causa confirmada (não suposição) → correção aplicada → se algo ficou dependendo de ação humana (ex.: rodar de novo pra confirmar, decidir um valor de negócio).

Fora de escopo do modo manual

A captura do fato bruto já é automática (ver Passo 0). O que continua manual é a investigação — decidir a causa real exige alguém (ou uma sessão do Claude) olhando de verdade; não tem como isso rodar sozinho. "Modo agendado" (rodar a suíte e processar falhas-pendentes.md sozinho, num horário fixo, sem ninguém pedir) é o próximo passo possível, ainda não implementado.