10 erros comuns em relatórios de bugs (e como evitá-los)

Um relatório de bug tem uma única tarefa: permitir que alguém que nunca viu o problema o reproduza à primeira tentativa. A maioria falha nisso, e raramente por falta de esforço. Falham por causa de um punhado de hábitos, repetidos por pessoas cuidadosas que nunca viram o seu próprio relatório aterrar na secretária de outra pessoa.

Cada detalhe deixado de fora custa segundos a escrever e horas a recuperar: uma ida e volta por um fio de comentários, um programador a construir um estado em que já estava sentado, um ticket fechado como não reproduzível e reaberto quinze dias depois por outra pessoa. É a única pessoa que alguma vez terá esse contexto de graça.

Dez hábitos, em dois grupos. Os primeiros seis são critério, e nenhuma ferramenta os fará algum dia por si. Os últimos quatro são contexto que existia no momento do bug e que ninguém anotou.

1. Um título que descreve uma sensação
2. Sem passos de reprodução
3. Sem comportamento esperado
4. Vários bugs num só ticket
5. Emoção em vez de impacto
6. Não procurar duplicados
7. Deixar de fora o ambiente
8. Descrever o que viu em vez de o mostrar
9. Saltar a consola e o separador de rede
10. “Funciona na minha máquina”, sem nada anexado

Se procura o método em vez das armadilhas, o artigo companheiro sobre como escrever um relatório de bug perfeito tem a anatomia de um bom relatório.

O que só você pode escrever

1. Um título que descreve uma sensação

“O checkout está partido.” “O login não funciona.” “Passa-se alguma coisa com as imagens.”

Um título é lido muitas vezes e aberto uma. Aparece nos resultados de pesquisa, nas reuniões diárias, nas notas de versão e na lista que alguém percorre enquanto decide o que pega esta manhã. Um título que poderia descrever quarenta defeitos diferentes torna cada um desses momentos mais lento.

O padrão é o que se partiu, mais onde ou quando, mais o único detalhe que separa o seu caso do de toda a gente a quem funciona.

Fraco

Imagens partidas

Melhor

As imagens de produto não carregam no Chrome móvel quando a página é aberta a partir da pesquisa

Procure uma frase que alguém consiga repetir em voz alta sem abrir o ticket.

2. Sem passos de reprodução

Sem passos, um programador não está a depurar, está a adivinhar o que fez. Cada palpite errado acaba em cannot reproduce, o ticket volta para si, e o relógio recomeça.

Os passos têm de começar num estado que qualquer pessoa consiga alcançar.

Fraco

Vai ao meu carrinho e tenta pagar

Melhor

1. Entrar como cliente com o carrinho vazio. 2. Adicionar dois artigos quaisquer. 3. Aplicar o código SAVE10. 4. Clicar em Continuar para pagamento.

Quatro linhas, e quem lê está onde você estava. Dê os seus próprios passos a um colega que não viu o bug. Se voltar com uma pergunta, a pergunta é o seu passo em falta.

3. Sem comportamento esperado

“O total está errado” assume que quem lê sabe qual é o certo. Muitas vezes não sabe, e por vezes aquilo que está a reportar acaba por ser uma regra que desconhecia.

Escreva as duas metades.

Fraco

O desconto está errado

Melhor

Esperado: o total mostra 45,00 depois dos 10 % de desconto. Real: o total mostra 50,00 e a linha do desconto não aparece.

É também assim que descobre que você e o programador discordam sobre para que serve a funcionalidade, uma conversa que vale mais ter no ticket do que três semanas depois.

4. Vários bugs num só ticket

Abrir três problemas juntos parece eficiente. Não é, porque um ticket tem um estado. Quando dois dos três estão corrigidos, o ticket não está feito nem por fazer, e o terceiro problema desaparece em silêncio debaixo de uma conversa que se lê como terminada.

Um defeito por ticket. Se partilham a causa, diga-o e ligue-os.

5. Emoção em vez de impacto

“Isto é inutilizável.” “Como é que isto chegou a sair?” “Terceira vez esta semana.”

A frustração é legítima. Um bug acabou de lhe comer a tarde. Mas empurra para fora a informação que faria a coisa ser corrigida, e põe quem lê na defensiva exatamente quando precisa da atenção dele no problema.

O impacto pertence a um relatório de bug. Enuncie-o como facto, e dê a quem faz a triagem o suficiente para definir uma prioridade sem adivinhar: quantas pessoas são afetadas, com que frequência, se há dinheiro ou dados envolvidos, se existe uma forma de contornar e se antes funcionava.

Fraco

Isto é um desastre, corrijam já

Melhor

Bloqueia o pagamento a todos os clientes de Safari, sem alternativa, começou depois da versão de terça

O segundo é bastante mais alarmante do que o primeiro, e bastante mais provável de ser pegado hoje. Um bug que impede uma pessoa de mudar o avatar e um bug que impede todos os clientes de pagar nunca deviam chegar com o mesmo aspeto.

6. Não procurar duplicados

Os duplicados custam duas vezes: uma quando alguém tria um relatório que já era conhecido, e outra quando a discussão de um problema fica dividida por dois tickets e nenhum guarda a história inteira.

Procure no tracker a mensagem de erro, o nome da página, e uma ou duas palavras do título que ia escrever. Procure também nos tickets fechados, porque um bug que foi corrigido e voltou é uma regressão, e dizê-lo muda a forma como é tratado.

Procurar é também a maneira mais rápida de aprender as palavras que a sua equipa usa de facto. Se toda a gente lhe chama cesto e você lhe chama carrinho, o seu relatório não será encontrado pela próxima pessoa a procurar, e você não encontrará o dela.

O que o navegador já sabe

Os quatro seguintes são de outra natureza. Ninguém deixa de fora a versão do navegador para poupar esforço. Deixa-a de fora porque registá-la significa sair da página, caçar uma cadeia de versão e escrevê-la num formulário, e a essa altura o separador está fechado.

7. Deixar de fora o ambiente

Um bug que acontece em todo o lado e um bug que acontece num só navegador são bugs diferentes com causas diferentes, e ninguém consegue dizer qual deles tem até alguém verificar. É assim que um relatório é fechado como não reproduzível: o programador tentou no Chrome, e você estava no Safari.

Registe o navegador e a sua versão, o sistema operativo, o dispositivo, e o tamanho da janela se o layout estiver minimamente envolvido. Latest Chrome não é uma versão. Quer dizer uma coisa diferente no dia em que é lido e no dia em que foi escrito.

8. Descrever o que viu em vez de o mostrar

A prosa é um formato com perdas para um problema visual. “O layout fica estranho mais abaixo” pode querer dizer meia dúzia de coisas, e essa meia dúzia tem correções diferentes.

Uma captura de ecrã resolve de imediato problemas de layout e de texto. Uma gravação curta é melhor para tudo o que envolva tempos, animação ou uma sequência de interações. Capture a janela inteira em vez de um recorte da parte partida: a barra de endereço, a consola e a página em redor contêm muitas vezes a resposta.

9. Saltar a consola e o separador de rede

É a primeira coisa que um programador pede e a última que a maioria dos relatórios inclui. Um erro a vermelho na consola normalmente nomeia o ficheiro e a linha que falham. Um pedido falhado no separador de rede normalmente nomeia o código de estado e o endpoint. Qualquer um dos dois pode transformar uma tarde de bissecção numa correção de dois minutos.

Abra as ferramentas de programador antes de fechar o separador. Copie o texto do erro em vez de o fotografar, para que possa ser pesquisado. Se um pedido falhou, anote o estado e o caminho.

10. “Funciona na minha máquina”, sem nada anexado

A frase termina uma conversa sem resolver nada, e funciona nos dois sentidos. Vinda de um programador quer dizer que ao relatório faltava o detalhe para reproduzir. Vinda de quem reporta, responder a uma correção com “continua partido para mim” e mais nada quer dizer exatamente o mesmo ao contrário.

De qualquer forma a resposta é prova em vez de afirmação: a versão que testou, o ambiente em que a testou, e o que viu. Um relatório sobre uma correção falhada merece o mesmo cuidado que o original.

O que resolve mesmo metade disto

Volte ao segundo grupo. Os erros 7, 8, 9 e 10 são um só problema com quatro chapéus: o contexto existia no momento do bug, e ninguém o anotou.

É essa a parte que vale a pena automatizar, e é por isso que construímos o Session Replay.

Não sabe em que clicou. Sabe o que o navegador sabia. Por isso não lhe escreve o título, não parte os seus três bugs em três tickets nem lhe diz o que esperava que acontecesse. Isso é critério, e continua a ser seu. O que remove é a desculpa para os quatro hábitos que sempre foram só atrito, o que lhe deixa os seis que são sobre pensar com clareza.

A lista de verificação

Antes de carregar em enviar:

• O título diz o que falhou, onde, e em que condição
• Os passos começam num estado que qualquer pessoa consegue alcançar
• O comportamento esperado e o real estão ambos escritos
• Um defeito neste ticket, e apenas um
• Impacto enunciado como facto, com o suficiente para outra pessoa definir a prioridade
• Procurei um relatório existente nos tickets abertos e fechados
• Navegador, versão, sistema operativo e dispositivo estão registados
• Está anexada uma captura ou gravação que mostra a janela inteira
• Os erros de consola e os pedidos falhados estão copiados como texto
• Prova para tudo o que afirmo, incluindo “continua a acontecer”