Depuração e Recuperação de Erros

Visão Geral

Depuração sistemática com triagem estruturada. Quando algo quebra, pare de adicionar funcionalidades, preserve evidências e siga um processo estruturado para encontrar e corrigir a causa raiz. Adivinhar desperdiça tempo. A lista de verificação de triagem funciona para falhas de teste, erros de compilação, bugs em tempo de execução e incidentes de produção.

Quando Usar

• Testes falham após uma alteração de código
• A compilação quebra
• O comportamento em tempo de execução não corresponde às expectativas
• Um relatório de bug chega
• Um erro aparece em logs ou no console
• Algo funcionava antes e parou de funcionar

A Regra "Pare a Linha"

Quando algo inesperado acontecer:

1. STOP adding features or making changes
2. PRESERVE evidence (error output, logs, repro steps)
3. DIAGNOSE using the triage checklist
4. FIX the root cause
5. GUARD against recurrence
6. RESUME only after verification passes

Não avance além de um teste falho ou compilação quebrada para trabalhar na próxima funcionalidade. Erros se acumulam. Um bug na Etapa 3 que não é corrigido torna as Etapas 4-6 incorretas.

A Lista de Verificação de Triagem

Trabalhe nestas etapas em ordem. Não pule etapas.

Etapa 1: Reproduzir

Faça a falha acontecer de forma confiável. Se você não conseguir reproduzi-la, não poderá corrigi-la com confiança.

Can you reproduce the failure?
├── YES → Proceed to Step 2
└── NO
    ├── Gather more context (logs, environment details)
    ├── Try reproducing in a minimal environment
    └── If truly non-reproducible, document conditions and monitor

Quando um bug não é reproduzível:

Cannot reproduce on demand:
├── Timing-dependent?
│   ├── Add timestamps to logs around the suspected area
│   ├── Try with artificial delays (setTimeout, sleep) to widen race windows
│   └── Run under load or concurrency to increase collision probability
├── Environment-dependent?
│   ├── Compare Node/browser versions, OS, environment variables
│   ├── Check for differences in data (empty vs populated database)
│   └── Try reproducing in CI where the environment is clean
├── State-dependent?
│   ├── Check for leaked state between tests or requests
│   ├── Look for global variables, singletons, or shared caches
│   └── Run the failing scenario in isolation vs after other operations
└── Truly random?
    ├── Add defensive logging at the suspected location
    ├── Set up an alert for the specific error signature
    └── Document the conditions observed and revisit when it recurs

Para falhas de teste:

# Run the specific failing test
npm test -- --grep "test name"

# Run with verbose output
npm test -- --verbose

# Run in isolation (rules out test pollution)
npm test -- --testPathPattern="specific-file" --runInBand

Etapa 2: Localizar

Restrinja ONDE a falha acontece:

Which layer is failing?
├── UI/Frontend     → Check console, DOM, network tab
├── API/Backend     → Check server logs, request/response
├── Database        → Check queries, schema, data integrity
├── Build tooling   → Check config, dependencies, environment
├── External service → Check connectivity, API changes, rate limits
└── Test itself     → Check if the test is correct (false negative)

Use bisseção para bugs de regressão:

# Find which commit introduced the bug
git bisect start
git bisect bad                    # Current commit is broken
git bisect good <known-good-sha> # This commit worked
# Git will checkout midpoint commits; run your test at each
git bisect run npm test -- --grep "failing test"

Etapa 3: Reduzir

Crie o caso mínimo de falha:

• Remova código/configuração não relacionados até que apenas o bug permaneça
• Simplifique a entrada para o menor exemplo que aciona a falha
• Reduza o teste ao mínimo necessário para reproduzir o problema

Uma reprodução mínima torna a causa raiz óbvia e evita corrigir sintomas em vez de causas.

Etapa 4: Corrigir a Causa Raiz

Corrija o problema subjacente, não o sintoma:

Symptom: "The user list shows duplicate entries"

Symptom fix (bad):
  → Deduplicate in the UI component: [...new Set(users)]

Root cause fix (good):
  → The API endpoint has a JOIN that produces duplicates
  → Fix the query, add a DISTINCT, or fix the data model

Pergunte: "Por que isso acontece?" até chegar à causa real, não apenas onde ela se manifesta.

Etapa 5: Proteger Contra Recorrência

Escreva um teste que capture essa falha específica:

// O bug: títulos de tarefas com caracteres especiais quebraram a busca
it('encontra tarefas com caracteres especiais no título', async () => {

…