Depuração com evidências

Reproduzir o erro, ler a mensagem e a pilha, testar uma hipótese por vez e levar à IA evidências em vez de “não funciona”.

Cerca de 15 min · Revisado em

Ao final, você vai conseguir

  • Registrar esperado e observado e reproduzir um erro de propósito
  • Ler o tipo, a mensagem e a primeira linha da pilha de um erro
  • Confirmar uma hipótese com log, breakpoint ou teste, mudando uma coisa por vez
  • Pedir à IA hipóteses com formas de testá-las a partir das evidências
  • Fechar a investigação com a menor correção e um teste de regressão

Todo mundo que programa passa boa parte do tempo procurando erros, inclusive quem tem anos de experiência. A diferença está no método: quem depura bem não sai mudando coisas até funcionar, e sim junta pistas, testa uma suspeita por vez e confirma a causa. Esse método também muda o que você recebe de uma IA. “Não funciona” rende um chute; a mensagem de erro, os passos e o que você esperava rendem uma investigação de verdade.

Por que “não funciona” não ajuda

Depurar é encontrar e corrigir a causa de um comportamento errado. O ponto de partida é sempre o mesmo par: o esperado (o que deveria acontecer) e o observado (o que acontece de fato). Sem os dois escritos, nem você nem a IA sabem o que procurar.

Uma evidência é algo que qualquer pessoa consegue ver ou repetir: uma mensagem de erro, a saída de um comando, um valor impresso no console. Uma opinião, como “acho que é o servidor”, pode até estar certa, mas ainda não foi confirmada.

Você vai pedir ajuda com um bug. O que é evidência e o que é só suspeita ou ruído?

Evidência · Suspeita ou ruído

  • A mensagem de erro completa, copiada do console
  • Os passos exatos que fazem o erro aparecer
  • O valor de uma variável impresso com console.log
  • Esperado: total R$ 16,00. Observado: tela em branco
  • “Deve ser algum problema do navegador”
  • “Funcionava ontem e hoje parou do nada”
  • Uma captura de tela cortada, sem a mensagem de erro

Primeiro, faça o erro acontecer de novo

Reproduzir é conseguir fazer o erro aparecer de propósito, quantas vezes quiser. Um erro que você reproduz já está meio resolvido: você consegue testar cada suspeita e, no final, provar que a correção funcionou.

  1. Anote os passos

    Comece de um estado conhecido, como a página recém-aberta, e escreva cada ação: “abro o carrinho com 3 itens, clico em Ver resumo”.

  2. Escreva esperado e observado

    Uma frase para cada. Se aparecer uma mensagem de erro, copie inteira, como texto, e não só o pedaço que parece importante.

  3. Diminua o caso

    Tente com menos dados e menos passos até sobrar o mínimo que ainda dá erro. Isso se chama reprodução mínima. Muitas vezes, ao diminuir, você já enxerga a causa.

  4. Tire o que é privado

    Antes de mostrar para alguém ou para a IA, troque senhas, tokens e dados pessoais por valores de exemplo, como você viu na aula sobre contexto e dados protegidos.

Coloque em ordem o método de depuração com evidências.

  • Reproduzir o erro e anotar os passos
  • Escrever o esperado e o observado
  • Ler a mensagem de erro e achar a linha onde quebrou
  • Levantar hipóteses e um jeito de testar cada uma
  • Mudar uma coisa só e verificar o resultado
  • Criar um teste que falharia sem a correção

Lendo a mensagem de erro

Mensagens de erro assustam no começo porque são longas e em inglês. Mas elas seguem sempre o mesmo formato, e a parte que importa costuma estar nas duas primeiras linhas. A lista de linhas com at se chama pilha de chamadas (em inglês, stack trace): o caminho que o programa percorreu até quebrar.

Um erro de JavaScript como aparece no console do navegador.

TypeError: Cannot read properties of undefined (reading 'preco')
    at somarCarrinho (carrinho.js:4:30)
    at atualizarResumo (pagina.js:12:17)
    at HTMLButtonElement.<anonymous> (pagina.js:20:3)
  • Tipo do erro: TypeError quer dizer que você tentou usar um valor de um jeito que o tipo dele não permite. Outros comuns são ReferenceError (nome que não existe) e SyntaxError (código escrito errado).
  • Mensagem: Traduzindo: “não dá para ler propriedades de undefined (lendo preco)”. Ou seja, em algum lugar existe algo.preco e esse algo está vazio. Já é uma pista enorme.
  • Onde quebrou: A primeira linha com at é o ponto exato da falha: função somarCarrinho, arquivo carrinho.js, linha 4, coluna 30. Comece a investigação por aqui.
  • Quem chamou: As linhas seguintes mostram quem chamou quem: um clique no botão chamou atualizarResumo, que chamou somarCarrinho. Útil para saber de onde vieram os dados que causaram o problema.

Com o erro acima na tela, qual é o primeiro lugar do código para olhar?

  • A linha 4 de carrinho.js, onde algum algo.preco encontrou undefined
  • A linha 20 de pagina.js, porque é onde tudo começou
  • O CSS da página, porque o resumo não aparece na tela
  • Nenhum: a mensagem é técnica demais e é melhor reescrever a função

Hipóteses e uma mudança por vez

Uma hipótese é uma explicação que pode ser testada: “acho que o laço passa do último item”. O que transforma hipótese em causa confirmada é uma verificação, como um console.log no lugar certo, um ponto de parada (breakpoint) no DevTools ou um teste. Acompanhe o código que gerou o erro da seção anterior.

Seguindo o laço passo a passo até o erro

function somarCarrinho(itens) {
  let total = 0;
  for (let i = 0; i <= itens.length; i++) {
    total = total + itens[i].preco;
  }
  return total;
}
console.log(somarCarrinho([{ preco: 5 }, { preco: 8 }, { preco: 3 }]));
  1. Linha 8: A função é chamada com três itens. As posições de uma lista começam em 0, então elas são 0, 1 e 2.
  2. Linha 2: O total começa em zero.
  3. Linha 3: i começa em 0. A condição 0 <= 3 é verdadeira, então o laço roda.
  4. Linha 4: Soma o preço do item 0.
  5. Linha 4: O laço roda de novo com i valendo 1 e depois 2. Os preços 8 e 3 são somados e tudo vai bem.
  6. Linha 3: i vira 3. E 3 <= 3 também é verdadeiro: o laço roda mais uma vez, para uma posição que não existe.
  7. Linha 4: itens[3] é undefined, e ler .preco de undefined quebra o programa. A hipótese “o laço passa do último item” está confirmada. Saída: TypeError: Cannot read properties of undefined (reading 'preco')
Qual é a menor correção possível, e como você provaria que ela funciona?

Trocar <= por < na linha 3: o laço passa a parar no item 2. A prova é rodar de novo o mesmo caso e ver 16 no console, e então criar um teste que soma esses três itens. Repare que a correção é um caractere. Reescrever a função inteira esconderia isso.

Você suspeitava de duas causas, trocou as duas ao mesmo tempo e o erro sumiu. Qual o problema disso?

  • Você não sabe qual das mudanças resolveu, e a outra pode ter criado um problema novo
  • Nenhum: o importante é que funcionou
  • O problema é só que o commit fica maior

Levando as evidências para a IA

Com reprodução, esperado, observado e a mensagem de erro em mãos, a IA vira uma boa parceira de investigação. O pedido certo não é “conserta”, e sim “me ajude a confirmar a causa”.

Um pedido de depuração com evidências

Problema reproduzível: abro o carrinho com 3 itens e clico em "Ver resumo".
Esperado: o resumo mostra o total 16.
Observado: nada aparece e o console mostra:
TypeError: Cannot read properties of undefined (reading 'preco')
    at somarCarrinho (carrinho.js:4:30)
Contexto: [trecho de carrinho.js, sem dados reais].
Liste até três hipóteses e uma verificação para distinguir cada uma.
Primeiro vamos confirmar a causa. Depois proponha a menor correção
e um teste de regressão.

Mesmo com um bom pedido, a resposta da IA é uma hipótese. Ela pode soar convincente e estar errada, porque a ferramenta prevê uma explicação plausível sem ter rodado o seu código.

A IA responde: “O problema é que o preço vem como texto. Use Number(itens[i].preco).” O que você faz?

  • Trata como hipótese e confere antes: imprime i e itens[i] no laço para ver o que chega
  • Aplica a sugestão, porque a explicação faz sentido
  • Pede para a IA reescrever a função inteira de outro jeito
  • Coloca um try/catch em volta do laço para o erro parar de aparecer

Mão na massa: investigue com console.log

Agora é com você. O carrinho da padaria deveria contar 5 itens, mas mostra outra coisa. Nada quebra, não há mensagem de erro: só um resultado estranho. Use console.log para olhar os valores por dentro antes de mudar qualquer coisa.

O carrinho que conta errado

Rode e compare o observado com o esperado (5). Investigue com console.log, por exemplo imprimindo item.qtd e typeof item.qtd dentro do laço. Depois faça a menor correção.

// Os dados chegam de um formulário:
// tudo o que se digita num campo chega como texto.
const carrinho = [
  { nome: 'Pão francês', qtd: '2' },
  { nome: 'Leite', qtd: '1' },
  { nome: 'Café', qtd: '2' },
];

function contarItens(itens) {
  let total = 0;
  for (const item of itens) {
    total = total + item.qtd;
  }
  return total;
}

// Esperado: 5
console.log('Itens no carrinho:', contarItens(carrinho));
  • O console mostra pelo menos uma linha de investigação, além do resultado
  • contarItens(carrinho) devolve o número 5
  • O console mostra Itens no carrinho: 5
  • A função continua certa com outros carrinhos, inclusive vazio
Por que o resultado era 0212, e não um erro?

Porque em JavaScript o + entre um número e um texto junta os dois como texto: 0 + "2" vira "02", depois "021", depois "0212". Nenhuma regra foi quebrada, então não há mensagem de erro. Bugs silenciosos como esse só aparecem quando você compara o observado com o esperado, e um typeof no console mostra a causa em segundos.

Fechamento

  • Depurar começa com esperado e observado escritos, e com o erro reproduzido de propósito.
  • Na mensagem de erro, leia o tipo, a mensagem e a primeira linha da pilha: elas dizem o que quebrou e onde.
  • Uma hipótese só vira causa depois de verificada com log, breakpoint ou teste; mude uma coisa por vez.
  • Dê à IA as evidências e peça hipóteses com formas de testá-las; trate a resposta como suspeita até conferir.
  • Feche a investigação com a menor correção e um teste de regressão.

Plante um bug e investigue com método

No projeto de laboratório da sua trilha, introduza de propósito um bug pequeno, como um <= no lugar de <, um campo com nome trocado ou um número que chega como texto. Depois investigue como se não soubesse a causa, com uma IA como parceira.

  1. Escreva os passos para reproduzir, o esperado e o observado, com a mensagem de erro completa e sem dados privados
  2. Peça à IA até três hipóteses e uma forma de testar cada uma
  3. Confirme ou descarte cada hipótese com um log, um breakpoint ou um teste, mudando uma coisa por vez
  4. Aplique a menor correção e escreva um teste que falha antes dela e passa depois
  5. Anote qual sugestão da IA estava certa, qual estava errada e que evidência mostrou isso

Referências

Cursos relacionados