Um relatório de bug é um conjunto de instruções para reproduzir algo que já viu. Foi bem sucedido quando alguém que não estava presente consegue provocar a mesma coisa à primeira tentativa, e falhou quando essa pessoa tem de voltar para lhe fazer uma pergunta.
Tudo o que se segue está escrito a partir desse único teste. Sete coisas a que um relatório tem de responder, um modelo que as pede por ordem e um relatório verdadeiro reescrito a partir da versão que teria sido devolvida.
Se procura o argumento sobre por que razão os relatórios falham em vez dos requisitos em si, o artigo companheiro sobre os dez erros comuns em relatórios de bugs trata dos hábitos que mais tempo custam.
A que tem de responder um relatório
O título
Um título é lido muitas vezes e aberto uma. Aparece na pesquisa, nas reuniões diárias, nas notas de versão e na lista que alguém percorre enquanto escolhe o que pegar. Escreva-o como aquilo que falhou, mais onde ou quando, mais o detalhe que separa o seu caso do de toda a gente a quem funciona.
- Fraco
- Login avariado
- Melhor
- Botão de entrada não responde depois de introduzir as credenciais no Firefox 121, Windows 11
Os passos
Numere-os e comece de um estado que qualquer pessoa consiga alcançar. Não “vá à minha conta”, mas a autenticação, os dados e cada acção pela ordem em que a fez. Termine com o que viu, para que quem lê saiba quando chegou.
1. Abrir https://example.com/login
2. Introduzir o email test@example.com e a palavra-passe TestPass123!
3. Clicar em Entrar
4. Observação: o botão mostra um breve estado de carregamento e volta ao normal. Não navega.
Entregue-os a alguém que não tenha visto o bug. Se essa pessoa lhe perguntar alguma coisa, a resposta é o seu passo em falta.
Comportamento esperado e comportamento real
Escreva os dois. “O login não funciona” parte do princípio de que quem lê sabe como é quando funciona, e às vezes aquilo que está a reportar acaba por ser uma regra que desconhecia.
- Esperado
- O utilizador é encaminhado para /dashboard depois de uma autenticação bem sucedida
- Real
- O botão carrega durante cerca de um segundo, volta ao estado normal e a página não muda
O ambiente
Um defeito que acontece em todo o lado e um defeito que acontece num só navegador têm causas diferentes, e ninguém consegue dizer qual é o seu até alguém verificar. Registe o navegador e a sua versão, o sistema operativo, o dispositivo e o tamanho da janela se o layout estiver envolvido.
Chrome mais recente não é uma versão. Quer dizer uma coisa no dia em que o escreve e outra no
dia em que é lido.
Provas visuais
Uma captura de ecrã resolve de imediato um problema de layout ou de texto. Uma gravação é melhor para tudo o que envolva tempos, animação ou uma sequência. Capture a janela inteira em vez do canto avariado: a barra de endereço, a consola e o resto da página são muitas vezes onde está a resposta.
A consola e o separador de rede
A primeira coisa que quem programa pede, e a última que a maioria dos relatórios inclui. Abra as ferramentas de programação antes de fechar o separador: F12, ou Cmd + Option + I num Mac.
Copie o texto do erro em vez de o fotografar, para que se possa pesquisar, e anote o estado e o caminho de qualquer pedido que tenha falhado.
POST https://example.com/api/auth/login 403 (Forbidden)
Error: Authentication failed: Invalid CSRF token
at login.js:45
O impacto
A prioridade não é o mesmo que a sua urgência, e um relatório que não oferece sinal nenhum é triado por quem grita mais alto. Dê os factos que permitem a outra pessoa decidir: quantas pessoas são afectadas, se há dinheiro ou dados envolvidos, se existe uma forma de contornar e se antes funcionava.
“Bloqueia a entrada a todos os utilizadores do Firefox, sem alternativa, começou depois do lançamento desta tarde” é mais alarmante do que “urgente”, e é mais provável que seja pegado hoje.
O modelo
# Relatório de bug
## Título
[Título claro e descritivo - o que está avariado e onde]
## Descrição
[Panorama breve do problema - 1 a 2 frases]
## Passos para reproduzir
1. [Primeiro passo - a partir de um estado conhecido]
2. [Segundo passo - seja concreto quanto às acções]
3. [Terceiro passo - inclua os dados e valores usados]
4. [Passos adicionais conforme necessário]
5. [Passo final que provoca o bug]
## Comportamento esperado
[O que deveria acontecer segundo o desenho ou a lógica]
## Comportamento real
[O que acontece na realidade - descreva os sintomas]
## Ambiente
- **Navegador:** [Nome e versão do navegador]
- **Sistema operativo:** [Sistema e versão]
- **Dispositivo:** [Computador ou telemóvel e modelo]
- **Resolução do ecrã:** [Se for um problema de layout]
- **Estado do utilizador:** [Com ou sem sessão iniciada, perfil]
## Provas visuais
[Anexe capturas de ecrã ou vídeo]
- Captura 1: [Descrição]
- Captura 2: [Descrição]
- Vídeo: [Ligação ou anexo]
## Erros de consola
```
[Cole os erros da consola do navegador - F12 → separador Consola]
```
## Problemas de rede
[Chamadas à API falhadas no separador Rede - F12 → Rede]
## Impacto e gravidade
- **Gravidade:** [Crítica/Alta/Média/Baixa]
- **Utilizadores afectados:** [Todos / Utilizadores móveis / Um perfil específico / etc.]
- **Impacto no negócio:** [Receita perdida / Carga de suporte / etc.]
- **Alternativa:** [Sim/Não - se sim, descreva]
## Contexto adicional
- **Frequência:** [Sempre / Às vezes / Raramente]
- **Desde quando:** [Agora mesmo / Depois de uma actualização / Desde [data]]
- **Casos relacionados:** [Ligações para bugs semelhantes]
- **Outras notas:** [Qualquer outra informação relevante]
## Lista de verificação
- [ ] Testei num ambiente limpo (janela anónima ou privada)
- [ ] Incluí os passos para reproduzir
- [ ] Forneci os detalhes do ambiente
- [ ] Anexei capturas de ecrã ou vídeo
- [ ] Verifiquei a consola à procura de erros
- [ ] Verifiquei se o problema já tinha sido reportado
O mesmo bug, reportado duas vezes
A primeira versão é a que costuma chegar. A segunda é a mesma pessoa, o mesmo defeito, quatro minutos depois.
- Fraco
- Login avariado. Não consigo entrar. Arranjem isto por favor!!!
- Melhor
- Botão de entrada não responde depois de introduzir as credenciais no Firefox 121, Windows 11
O segundo relatório traz o resto: os quatro passos acima, o comportamento esperado e o real, Firefox 121 em Windows 11 Pro a 1920x1080 numa janela privada sem extensões, duas capturas de ecrã e uma gravação de quinze segundos, o erro de CSRF da consola e uma linha sobre a gravidade - todos os utilizadores, sem alternativa, começou depois do lançamento das 14:30.
Nada disso exigiu pesquisa. Estava tudo no ecrã enquanto o bug acontecia, e cada uma dessas peças desapareceu no momento em que o separador foi fechado.
De onde vem o contexto
Repare no que o segundo relatório contém. O título, os passos e o comportamento esperado são critério, e esse é seu. O ambiente, a captura de ecrã, o erro de consola e o pedido falhado não são critério nenhum. Eram factos sobre o navegador no momento em que as coisas correram mal, e anotá-los à mão significa sair da página, procurar uma cadeia de versão e voltar a escrever um erro.
Session Replay
Extensão gratuita do Chrome. Um clique na página que se está a portar mal captura a captura de ecrã, a consola e o registo de rede, e devolve-lhe um link para colar no ticket.
Não escreve o seu título, não decide a sua gravidade nem separa dois defeitos em dois tickets. Essas são as partes que precisam de alguém que estava lá.