Como escrever um bug report que o dev consegue resolver
Como escrever um bug report que é corrigido: título específico, passos exatos para reproduzir, esperado versus obtido, dados do ambiente e evidências.
Para escrever um bug report com o qual os devs consigam trabalhar, primeiro reproduza o problema. Depois escreva um título específico de uma linha, o ambiente (URL, navegador e versão, sistema operacional, conta), passos numerados para reproduzir a partir de um ponto de partida conhecido, o resultado esperado, o resultado obtido com as mensagens de erro exatas, e anexe evidências como um screenshot ou uma gravação, os erros de console e a requisição de rede que falhou. Um bug por report.
O teste de um bom report é simples: um dev que nunca viu o problema conseguiria fazê-lo acontecer na própria máquina, sem perguntar nada a você? Se sim, o bug provavelmente vai ser corrigido rápido. Se ele precisar voltar com perguntas, cada ida e volta custa um dia. Se você quer os campos como checklist, copie o nosso modelo de bug report.
1. Reproduza antes de escrever
Tente fazer o bug acontecer uma segunda vez. Enquanto isso, preste atenção nos detalhes que podem importar:
- Qual conta ou papel você estava usando.
- Quais dados estavam envolvidos: um produto específico, um nome longo, uma lista vazia, um arquivo grande.
- Quais passos são realmente necessários. Remova os passos um por um para achar o caminho mais curto.
- Se acontece em outro navegador ou numa janela anônima.
Se acontece toda vez, ótimo. Se acontece só às vezes, conte: "4 de 10 tentativas". Se você não consegue reproduzir de jeito nenhum, reporte mesmo assim, e deixe isso claro.
2. Veja se já foi reportado
Pesquise no rastreador a mensagem de erro, o nome da página e algumas palavras-chave. Se encontrar um ticket correspondente, acrescente os seus detalhes a ele em vez de abrir um novo: o seu ambiente, um novo jeito de disparar o bug ou o fato de que ele ainda acontece na build mais recente. Duplicatas espalham a informação por vários tickets e desperdiçam tempo de triagem.
3. Escreva um título específico
O título muitas vezes é a única coisa que as pessoas leem na triagem. Faça-o descrever o problema, não a funcionalidade.
| Título fraco | Título melhor |
|---|---|
| Login quebrado | Login com Google volta para a página de login no Safari |
| Bug nos relatórios | Exportação em CSV do relatório de Vendas perde linhas depois da 1.000ª |
| Página lenta | Página de cobrança leva mais de 10 segundos para carregar em contas com muitas faturas |
| Erro ao salvar | Salvar um perfil com emoji no nome retorna "Invalid input" |
Um padrão útil: o que está quebrado, mais quando acontece, mais onde.
4. Descreva o ambiente
Muitos bugs só aparecem numa configuração específica. Inclua:
- URL da página onde aconteceu.
- Navegador e versão, por exemplo Chrome, Firefox, Safari ou Edge com o número da versão da página "Sobre".
- Sistema operacional e dispositivo.
- Tamanho da tela, se for um problema de layout.
- Versão ou build do app, se o app mostrar.
- Conta, papel ou usuário de teste, e qualquer coisa especial sobre ela (uma conta de teste grátis, uma organização grande, um idioma diferente do inglês).
- Horário em que aconteceu, com fuso horário, para que o time consiga encontrá-lo nos logs do servidor.
5. Escreva os passos para reproduzir
Os passos são o núcleo do report. Bons passos:
- Começam de um estado conhecido: "Logado como admin, no Dashboard".
- Usam uma ação por passo numerado.
- Nomeiam os dados exatos: o produto, o arquivo, o texto que você digitou. Nunca inclua senhas ou números de cartão reais; use dados de teste.
- Usam os rótulos que aparecem no app, em negrito ou entre aspas, para que o dev encontre o mesmo botão.
- Terminam no momento em que o bug aparece.
1. Faça login como [email protected] (papel Admin).
2. Vá em Settings e depois em Team.
3. Clique em "Invite member".
4. Digite "[email protected]" e escolha o papel "Viewer".
5. Clique em "Send invite".
6. Escreva o resultado esperado e o obtido
Coloque um ao lado do outro:
Esperado: O convite aparece na lista Pending e uma notificação de confirmação é exibida.
Obtido: O diálogo fecha, nenhuma notificação aparece e a lista Pending continua vazia.
Depois de recarregar, o convite continua faltando.
Descreva o que você observou, não o que você acha que causou o problema. "A requisição do convite falhou" é uma conclusão; "o diálogo fechou e nada apareceu na lista" é uma observação. Se você viu uma mensagem de erro, copie-a como texto, exatamente. Os devs procuram essa string no código.
7. Acrescente evidências
Evidências transformam uma descrição em prova e muitas vezes apontam direto para a causa.
- Screenshot com a área do problema destacada. Recorte dados pessoais que não tenham a ver com o bug.
- Gravação de tela para qualquer coisa que envolva movimento, tempo ou vários passos. Mantenha-a curta e comece logo antes do problema.
- Erros de console. Em apps web, um erro vermelho no console do navegador costuma ser a pista mais útil. Veja como exportar logs de console no Chrome.
- A requisição de rede que falhou. A URL, o status code e o body da resposta da chamada de API que falhou. Veja como capturar o tráfego de rede no Chrome.
- Um arquivo HAR, se o time pedir a sessão de rede inteira. Siga como obter um arquivo HAR e limpe-o antes com o sanitizador de HAR, porque arquivos HAR incluem cookies e tokens.
8. Avalie o impacto com honestidade
Diga o quanto é grave e quantas pessoas são afetadas. Use a escala de severidade do seu time, se houver uma. Seja honesto: se tudo é marcado como crítico, nada é. Mencione um contorno se você encontrou um; isso muda a urgência da correção e ajuda o suporte enquanto isso.
9. Um bug só
Se você encontrou três problemas na mesma página, escreva três reports. Assim cada um pode ser atribuído, corrigido, testado e fechado por conta própria. Ligue-os entre si se parecerem relacionados.
10. Fique disponível
Depois de enviar, acompanhe o ticket para responder a perguntas. Quando a correção sair, teste de novo com os mesmos passos e confirme. Se o bug voltar mais tarde, reabra o ticket original ou crie um link para ele, para que o histórico fique num só lugar.
Erros comuns
- Títulos vagos como "não funciona" ou "problema na página".
- Passos faltando, ou passos que começam no meio de um fluxo.
- Screenshots de mensagens de erro em vez do texto, que não dá para pesquisar.
- Vários bugs num ticket só.
- Segredos reais no report: senhas, API keys, cookies de sessão ou dados de clientes em screenshots e logs.
- Linguagem emocional. Um report calmo e factual é corrigido mais rápido que um irritado.
Para reports bons e ruins lado a lado, veja os nossos exemplos de bug report.
Escreva menos, capture mais
A maior parte do esforço de um bug report vai para os detalhes técnicos, e são justamente eles que quem reporta esquece. O Midge, uma extensão grátis do Chrome, grava a sua tela ou tira um screenshot e anexa esses detalhes por você, então você só escreve o título, os passos e o que esperava. Toda gravação inclui logs de console, requisições de rede, ações do usuário e informações do dispositivo. Senhas, números de cartão, tokens e cookies são ocultados no seu navegador antes que qualquer coisa saia do seu dispositivo. O report é compartilhado como um único link que você pode colar no rastreador que o seu time usar.
Guias relacionados
Perguntas frequentes
Quais são as partes mais importantes de um bug report?
Os passos para reproduzir, o resultado esperado e o resultado obtido. Com esses três, um dev normalmente consegue ver o problema por conta própria. Dados do ambiente e evidências como screenshots e erros de console deixam tudo mais rápido.
Qual deve ser o tamanho de um bug report?
O mais curto possível, desde que completo. A maioria dos bons reports cabe numa tela: um título de uma linha, um resumo curto, de cinco a dez passos, o resultado esperado e o obtido, e os anexos.
E se eu não conseguir reproduzir o bug?
Reporte mesmo assim e diga isso. Descreva exatamente o que você estava fazendo, quando aconteceu, e anexe qualquer evidência que tiver, como um screenshot ou um erro de console. Marque a frequência como "aconteceu uma vez".
Devo incluir a minha opinião sobre a causa?
Mantenha observações e palpites separados. Escreva o que você viu nos campos principais e, se tiver uma teoria, acrescente-a numa seção de notas identificada como palpite.