Um bom relatório de bug é corrigido. Um ruim ganha o rótulo «não reproduzível», um pedido de mais informações que quem reportou nunca responde e uma morte lenta no fim do backlog. A diferença raramente está no esforço. Está em saber do que a pessoa que vai corrigir o bug precisa.
Este guia mostra a estrutura de um relatório que sobrevive à triagem, seja quando você mesmo o escreve, seja quando ensina usuários e colegas a escrever relatórios melhores.
A anatomia de um relatório útil
Um título que descreve a falha, não o sentimento
«O checkout está quebrado» não diz nada ao desenvolvedor. «Checkout: depois de aplicar um cupom de desconto, clicar em Pagar mostra um spinner infinito» diz onde procurar, o que tentar e dá uma pista do gatilho. Um bom título traz o local, a ação e o resultado observado.
Passos para reproduzir
Escreva a sequência mais curta que dispara o bug, a partir de um estado conhecido:
Faça login como cliente com um item no carrinho
Aplique o cupom de desconto SAVE10
Clique em Pagar
Os passos numerados importam porque quem for corrigir vai segui-los ao pé da letra. Se o passo 2 é essencial e você o omite, o bug se reproduz para você e não para a outra pessoa, e agora os dois estão travados.
Comportamento esperado e comportamento real
Duas linhas curtas: o que deveria ter acontecido e o que aconteceu no lugar disso. Parece burocracia até você topar com um bug em que cada um tem uma ideia diferente do que é o comportamento «correto». «Esperado: página de confirmação do pedido. Real: spinner infinito, nenhuma atividade de rede depois do clique» acaba com a ambiguidade.
O ambiente
Navegador e versão, sistema operacional, dispositivo, tamanho da tela e a URL exata da página. Uma quantidade enorme de bugs de front-end depende do ambiente: um problema de parsing de datas que só acontece no Safari, um layout que só quebra na largura de um tablet. Sem os dados do ambiente, o desenvolvedor testa no próprio navegador, não vê nada e fecha o relatório.
As evidências
É isso que separa um relatório que leva cinco minutos para diagnosticar de um que leva um dia:
Saída do console: a mensagem de erro e o stack trace reais, não uma paráfrase deles.
Atividade de rede: qual requisição falhou e com qual código de status.
Uma captura de tela ou gravação: principalmente em bugs visuais e de layout, em que mil palavras são mesmo piores que uma imagem.
Horário: quando aconteceu, para cruzar com os logs do servidor e com os deploys.
Por que os usuários não vão fazer nada disso
A parte incômoda é esta: faz sentido cobrar este checklist de um analista de QA, e é absurdo cobrá-lo de um usuário. Usuários não sabem o que é um console, não vão procurar a versão do navegador e não vão escrever passos para reproduzir. O melhor que conseguem, com toda a sinceridade, é «não funciona», e cada campo que você acrescenta ao formulário de bug faz você perder mais relatórios.
Você tem duas opções. Aceitar relatórios vagos e pagar o preço na triagem. Ou coletar automaticamente a metade técnica do relatório e deixar o usuário contribuir com a única coisa que só ele tem: o que estava tentando fazer.
É nesse modelo que se baseiam os widgets de relatório de bug. Com uma ferramenta como o BugDump, o usuário clica num botão e digita uma frase; o widget anexa sozinho os logs do console, as requisições de rede, o replay de sessão, os dados do ambiente e a URL da página. O usuário escreve «cliquei em pagar, não aconteceu nada», e tudo bem, porque a exceção não capturada e a requisição que falhou estão ali mesmo no relatório.
O checklist
Para relatórios que uma pessoa escreve do começo ao fim (QA interno, relatórios de colegas, issues no GitHub):
O título traz local + ação + resultado observado
Passos numerados para reproduzir, a partir de um estado inicial conhecido
Comportamento esperado, em uma linha
Comportamento real, em uma linha
Ambiente: navegador + versão, SO, dispositivo, viewport, URL
Erros do console, copiados literalmente
Requisição de rede que falhou e código de status, se houver
Captura de tela ou gravação para qualquer coisa visual
Severidade e impacto: quem é afetado e com que frequência?
Para relatórios coletados de usuários, o checklist muda de forma: a maioria dos itens deve ser marcada pelas ferramentas, não por pessoas:
Descrição nas palavras do próprio usuário (o único campo obrigatório)
Todo o resto (ambiente, console, rede, replay) capturado automaticamente
Identidade de quem reportou anexada automaticamente para usuários logados, para que dê para voltar a falar com a pessoa
Um relatório, um bug
Resista à tentação de juntar tudo. «O painel está lento, além disso o botão de exportar está quebrado e o modo escuro está esquisito» são três bugs vestidos com o ID de um único relatório. Um relatório agrupado não dá para priorizar (as severidades são diferentes), não dá para fechar (corrigir um bug deixa o relatório dois terços aberto) e não dá para atribuir direito. Abra três relatórios. Se o seu bug tracker organiza relatórios em tarefas — o BugDump transforma relatórios em cards num quadro kanban —, essa disciplina se paga na hora, porque cada card se move de forma independente.
Severidade honesta
Marque a severidade pelo impacto, não pela irritação. Um erro de digitação que você acha constrangedor é de baixa severidade; uma falha no pagamento que afeta um navegador é de alta severidade, mesmo que você não consiga reproduzi-la. Relatórios sempre marcados como «crítico» ensinam a equipe a ignorar o campo por completo, o que é pior do que não ter o campo.
O que se ganha com isso
Bons relatórios de bug têm efeito cumulativo. Cada relatório com evidências reais é corrigido mais rápido, o que mantém o backlog curto, o que mantém a triagem rápida, o que deixa mais tempo para os relatórios difíceis de verdade. E o hábito pega: desenvolvedores que recebem ótimos relatórios passam a escrevê-los.
Escreva o relatório que você gostaria de receber às 17h de uma sexta-feira, e automatize tudo o que quem reporta não deveria precisar saber fornecer.
Leia também
Modelo de relatório de bug que funciona (e como automatizar a maior parte) — os campos de um relatório e quais deles uma ferramenta deve preencher no lugar de uma pessoa.
Anatomia de um relatório de bug: o que o BugDump captura e por quê — que dados o widget do BugDump anexa a cada relatório e como cada um ajuda a achar a causa.
O que fazer com um relatório de bug que você não consegue reproduzir — o que verificar antes de fechar um relatório como «não reproduzível».