Pular para o conteúdo

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 fracoTítulo melhor
Login quebradoLogin com Google volta para a página de login no Safari
Bug nos relatóriosExportação em CSV do relatório de Vendas perde linhas depois da 1.000ª
Página lentaPágina de cobrança leva mais de 10 segundos para carregar em contas com muitas faturas
Erro ao salvarSalvar 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.