I filed a bug report with the exact error message and the steps to reproduce.
Abri um bug report com a mensagem de erro exata e os passos para reproduzir.Aula
Reportar bugs com precisão
Nível: B1
Objetivo
Escrever bug reports claros e completos em inglês, cobrindo environment, version, severity, expected behavior, actual behavior, steps to reproduce e evidências (screenshots/logs), evitando ambiguidade e acelerando a triagem do time.
Explicação
Um bug report bem escrito é aquele que um engenheiro consegue reproduzir sem precisar voltar para perguntar nada. Em times que trabalham em inglês, a estrutura recomendada é sempre a mesma, com sete blocos. Pular um bloco é o que cria ambiguidade.
1. Environment — onde o bug aconteceu. Inclua sistema operacional, navegador e versão, dispositivo, tipo de conexão e papel do usuário na aplicação:
- *Environment: Windows 11, Chrome 124.0, 1920×1080, on corporate Wi-Fi, logged in as an admin.*
- *Environment: macOS 14.4, Safari 17.4, iPhone 15 Pro, mobile data, regular user.*
2. Version — qual build, release ou commit estava em uso na hora do erro. Sem isso, ninguém sabe se o bug já foi corrigido ou se é uma regressão:
- *App version: 4.12.0 (build 48217), backend commit `a3f9c1d`.*
3. Severity — quão sério o bug é, em uma escala consistente do time. Termos comuns são blocker, critical, major, minor, trivial, e o time define a escala no CONTRIBUTING. Não confunda severity (impacto técnico) com priority (ordem de correção): um bug visual em uma landing page pode ser *minor* mas com *high priority* se está afetando uma campanha.
4. Expected behavior — o que deveria ter acontecido. Seja específico: qual elemento, qual texto, qual status code.
- *Expected: After clicking "Save", the form closes and a success toast appears.*
- *Expected: The API returns `200 OK` with the updated record in the body.*
5. Actual behavior — o que aconteceu de fato. Use o mesmo nível de detalhe do expected e, se possível, cite o erro exato:
- *Actual: The form stays open. The toast never appears. The console shows `TypeError: Cannot read properties of undefined (reading 'id')` at `Form.tsx:142`.*
6. Steps to reproduce — a sequência mínima de ações que produz o bug. Cada passo começa com um verbo imperativo e produz um resultado observável. Marque a reproduction rate (ex.: *Reproduces 3 out of 5 times*) quando o bug é intermitente:
- *Log in as a user with read-only role.*
- *Open the dashboard.*
- *Click on the "Export CSV" button.*
- *Wait for the download.*
- *Observe: the request hangs for 30 seconds, then the page shows a 500 error.*
7. Evidence — screenshots curtos, gravações de tela curtas, logs do console, stack traces, payloads de request/response. Marque áreas com retângulos vermelhos e use anotações curtas em vez de setas decorativas.
Evitar ambiguidade significa quatro coisas concretas. Primeiro, use nomes exatos em vez de pronomes vagos: *the export button*, nunca *it*. Segundo, separe observação de opinião: *The button does not respond to clicks* (observação), não *The button is broken* (opinião). Terceiro, cite mensagens de erro literais entre aspas, em vez de paráfrases. Quarto, declare o que você não testou: *I only tested on Chrome; I did not test on Firefox or Safari.*
Por fim, termine com workaround quando existir: *Reloading the page lets the export finish.* Mesmo um workaround ruim economiza tempo de quem está triando.
Exemplos
| Inglês | Tradução | Observação |
|---|---|---|
| Environment: Windows 11, Chrome 124.0, 1920x1080, corporate Wi-Fi, admin user. | Ambiente: Windows 11, Chrome 124.0, 1920x1080, Wi-Fi corporativo, usuário admin. | Cabeçalho Environment em uma só linha, com vírgulas. |
| App version: 4.12.0 (build 48217). Backend commit: a3f9c1d. | Versão do app: 4.12.0 (build 48217). Commit do backend: a3f9c1d. | Version inclui build number e commit quando disponíveis. |
| Severity: major. The export feature is unusable for read-only users. | Severidade: major. A funcionalidade de export está inutilizável para usuários read-only. | Severity vem com uma frase curta justificando o impacto. |
| Expected: clicking "Export CSV" downloads a file named report.csv within 5 seconds. | Esperado: clicar em "Export CSV" baixa um arquivo chamado report.csv em até 5 segundos. | Expected cita o nome do botão, o nome do arquivo e o tempo limite. |
| Actual: the request hangs for about 30 seconds and the UI shows "Something went wrong". | Atual: a requisição trava por cerca de 30 segundos e a UI mostra "Something went wrong". | Actual cita a mensagem literal entre aspas. |
| Steps to reproduce: 1) Log in as a read-only user. 2) Open the dashboard. 3) Click "Export CSV". 4) Wait 30 seconds. | Passos para reproduzir: 1) Faça login como usuário read-only. 2) Abra o dashboard. 3) Clique em "Export CSV". 4) Aguarde 30 segundos. | Passos numerados, um verbo imperativo por linha. |
| Reproduces 3 out of 5 times. The other 2 times, the file downloads correctly. | Reproduz em 3 de 5 tentativas. Nas outras 2, o arquivo baixa corretamente. | Reproduction rate para bugs intermitentes. |
| Workaround: reloading the page after the 500 error lets the export finish. | Workaround: recarregar a página depois do erro 500 faz o export terminar. | Workaround economiza tempo mesmo quando não há correção. |
Erros comuns
- Escrever "it doesn't work" ou "the app is broken" sem citar o botão, a tela ou o erro exato. Substitua pelo nome do componente e pela mensagem literal.
- Misturar severity com priority: *minor severity, high priority* é diferente de *critical severity, low priority*. Severidade mede impacto técnico; prioridade mede urgência de negócio.
- Paráfrase de mensagens de erro: troque *the server returns an error* pela string literal `"502 Bad Gateway: upstream timeout"`.
- Esquecer a versão do app ou do backend, especialmente em sistemas com release notes frequentes. Sem versão, o time não sabe se a correção já foi publicada.
- Pular passos de reprodução que assumem contexto ("do the usual setup"): o leitor não sabe qual setup é o usual. Liste cada clique e cada input.
- Marcar o bug como *regression* sem comparar com a versão anterior. Regression exige evidência: *This worked in 4.11.2 and started failing in 4.12.0.*
- Anexar uma screenshot sem anotar: peça para o leitor adivinhar onde olhar. Use retângulos vermelhos e legendas curtas.
- Não declarar o que não foi testado: adicionar *I did not test on Firefox or mobile* ajuda o time a decidir se precisa de mais validação.
Prática guiada
Reescreva este bug report vago em formato estruturado:
> *Hi, the export thing doesn't work on my machine. It's urgent, please fix. I think it started yesterday. See attached.*
Versão reescrita:
- Environment: macOS 14.4, Chrome 124.0, 1440x900, regular user account, on home Wi-Fi.
- Version: app 4.12.0, backend commit `a3f9c1d`.
- Severity: major. Affects all read-only users.
- Expected: clicking "Export CSV" downloads `report.csv` within 5 seconds.
- Actual: the request hangs for 30 seconds, then the UI shows the toast `"Something went wrong"`. The console prints `TypeError: Cannot read properties of undefined (reading 'id')`.
- Steps to reproduce: 1) Log in as a read-only user. 2) Open the dashboard. 3) Click "Export CSV". 4) Wait 30 seconds. Reproduces 5 out of 5 times on my machine.
- Evidence: screenshot.png, console.log attached.
- Workaround: reloading the page after the error lets the export finish.
- Not tested: Firefox, Safari, mobile.
A diferença não é o vocabulário sofisticado: é que cada afirmação do leitor pode ser verificada pelo time.
Resumo
Um bug report completo tem sete blocos: Environment, Version, Severity, Expected behavior, Actual behavior, Steps to reproduce e Evidence. Para evitar ambiguidade, cite nomes exatos, mensagens literais, reproduction rate, e declare o que não foi testado. Termine com um workaround quando existir.
Vocabulário
Palavras principais
'State the environment in the first line: OS, browser, device, network.'
'Declare o ambiente na primeira linha: SO, navegador, dispositivo, rede.'Always include the app version and the backend commit hash.
Sempre inclua a versão do app e o hash do commit do backend.The build number is 48217, released on 2024-05-12.
O número de build é 48217, lançado em 12/05/2024.'We classify this as severity: major because the feature is unusable.'
'Classificamos isso como severity: major porque a funcionalidade está inutilizável.'A production outage is a blocker and must be fixed before the release.
Uma queda em produção é blocker e precisa ser corrigida antes do release.A critical bug breaks a core flow for most users.
Um bug crítico quebra um fluxo principal para a maioria dos usuários.'Expected behavior: the form closes after a successful save.'
'Comportamento esperado: o formulário fecha depois de um save bem-sucedido.''Actual behavior: the form stays open and the toast never appears.'
'Comportamento atual: o formulário continua aberto e o toast não aparece.'List the steps to reproduce in numbered order, one verb per line.
Liste os passos para reproduzir em ordem numerada, um verbo por linha.The reproduction rate is 3 out of 5 attempts on the same device.
A taxa de reprodução é 3 de 5 tentativas no mesmo dispositivo.Attach a screenshot with the error message highlighted in a red box.
Anexe uma captura de tela com a mensagem de erro destacada em um retângulo vermelho.The stack trace points to Form.tsx:142 in the validation module.
O stack trace aponta para Form.tsx:142 no módulo de validação.Paste the relevant lines from the server log, not the whole file.
Cole as linhas relevantes do log do servidor, não o arquivo inteiro.The console output shows a TypeError when the button is clicked.
A saída do console mostra um TypeError quando o botão é clicado.'This is a regression: it worked in 4.11.2 and started failing in 4.12.0.'
'Esta é uma regressão: funcionava na 4.11.2 e começou a falhar na 4.12.0.'An intermittent bug is harder to reproduce, so the rate matters.
Um bug intermitente é mais difícil de reproduzir, por isso a taxa importa.A reproducible bug is much easier to triage than a one-off glitch.
Um bug reproduzível é muito mais fácil de triar do que uma falha pontual.História
História: Reportar bugs com precisão
Nível: B1
História em inglês
A vague report
On Monday morning, the support channel received three messages about the export feature. Each message said the same thing: "the export doesn't work". Nina, the on-call engineer, opened a ticket titled "Export broken, please fix ASAP". She had no version, no environment, no steps, and no error message. She spent forty minutes asking the reporter for the basic information.
A precise report
Then a fourth message arrived, this time with a full report. It started with: "Environment: macOS 14.4, Chrome 124.0, regular user, on home Wi-Fi." The version line read: "App 4.12.0, build 48217, backend commit a3f9c1d." Severity was marked as major, with a short note: "export is unusable for read-only users". Expected behavior: "clicking 'Export CSV' downloads report.csv within 5 seconds." Actual behavior: "the request hangs for 30 seconds, then the UI shows 'Something went wrong'." The console printed "TypeError: Cannot read properties of undefined (reading 'id')".
Reproducing and fixing
The steps to reproduce were four clean lines, each starting with a verb. The reproduction rate was 5 out of 5 on the same device. Nina reproduced the bug in two minutes and found the missing null check. The reporter had also included a workaround: reloading the page after the error. Nina published a fix the same day and thanked the reporter for the precise report. She added: "this is the standard we want from every bug report on this team".
Tradução linha por linha
| Inglês | Tradução |
|---|---|
| On Monday morning, the support channel received three messages about the export feature. | Na segunda de manhã, o canal de suporte recebeu três mensagens sobre a funcionalidade de export. |
| Each message said the same thing: "the export doesn't work". | Cada mensagem dizia a mesma coisa: "o export não funciona". |
| Nina, the on-call engineer, opened a ticket titled "Export broken, please fix ASAP". | Nina, a engenheira de plantão, abriu um ticket chamado "Export quebrado, por favor, corrigir ASAP". |
| She had no version, no environment, no steps, and no error message. | Ela não tinha versão, ambiente, passos e nem mensagem de erro. |
| She spent forty minutes asking the reporter for the basic information. | Ela gastou quarenta minutos pedindo ao reportador as informações básicas. |
| Then a fourth message arrived, this time with a full report. | Aí chegou uma quarta mensagem, dessa vez com um report completo. |
| It started with: "Environment: macOS 14.4, Chrome 124.0, regular user, on home Wi-Fi." | Começava com: "Environment: macOS 14.4, Chrome 124.0, usuário comum, em Wi-Fi residencial." |
| The version line read: "App 4.12.0, build 48217, backend commit a3f9c1d." | A linha de versão dizia: "App 4.12.0, build 48217, commit do backend a3f9c1d." |
| Severity was marked as major, with a short note: "export is unusable for read-only users". | A severidade estava marcada como major, com uma nota curta: "export está inutilizável para usuários read-only". |
| Expected behavior: "clicking 'Export CSV' downloads report.csv within 5 seconds." | Comportamento esperado: "clicar em 'Export CSV' baixa o report.csv em até 5 segundos." |
| Actual behavior: "the request hangs for 30 seconds, then the UI shows 'Something went wrong'." | Comportamento atual: "a requisição trava por 30 segundos, depois a UI mostra 'Something went wrong'". |
| The console printed "TypeError: Cannot read properties of undefined (reading 'id')". | O console imprimia "TypeError: Cannot read properties of undefined (reading 'id')". |
| The steps to reproduce were four clean lines, each starting with a verb. | Os passos para reproduzir eram quatro linhas limpas, cada uma começando com um verbo. |
| The reproduction rate was 5 out of 5 on the same device. | A taxa de reprodução era 5 de 5 no mesmo dispositivo. |
| Nina reproduced the bug in two minutes and found the missing null check. | Nina reproduziu o bug em dois minutos e encontrou a null check que faltava. |
| The reporter had also included a workaround: reloading the page after the error. | O reportador também tinha incluído um workaround: recarregar a página depois do erro. |
| Nina published a fix the same day and thanked the reporter for the precise report. | Nina publicou uma correção no mesmo dia e agradeceu ao reportador pelo report preciso. |
| She added: "this is the standard we want from every bug report on this team". | Ela acrescentou: "esse é o padrão que queremos de todo bug report neste time". |
Notas de vocabulário
- the export doesn't work = frase vaga típica; não cita botão, tela, erro ou ambiente
- Environment: macOS 14.4, Chrome 124.0 = cabeçalho Environment com SO, navegador, dispositivo, rede e papel
- App 4.12.0, build 48217, backend commit a3f9c1d = linha de Version com app version, build number e commit
- Severity: major = uma das cinco categorias comuns: blocker, critical, major, minor, trivial
- the request hangs for 30 seconds = hangs descreve uma requisição que não responde; citar o tempo ajuda a triar
- TypeError: Cannot read properties of undefined = mensagem de erro literal; deve ser citada entre aspas no report
- 5 out of 5 on the same device = reproduction rate para diferenciar bug consistente de bug intermitente
- workaround: reloading the page = solução de contorno que mantém o usuário produtivo enquanto a correção não sai
Perguntas de compreensão
- What was wrong with the first three bug reports?
- How long did Nina spend asking the first reporter for details?
- What environment did the fourth reporter describe?
- What app version and build number did the fourth report include?
- What was the expected behavior of the export button?
- What error did the browser console print?
- What was the reproduction rate on the reporter's device?
- How long did Nina take to reproduce the bug from the precise report?
- What workaround did the reporter include?
- What did Nina say about the standard for bug reports on the team?
Prática com a história
- Reescreva a primeira frase vaga "the export doesn't work" como uma linha de Actual behavior.
- Traduza: Severidade: major. A exportação está inutilizável para usuários read-only.
- Escreva uma linha de Environment para um teste em Windows, Chrome, usuário admin, conexão cabeada.
- Dê um exemplo de reproduction rate para um bug intermitente.
Prática
Exercícios e teste
A próxima melhoria é transformar esses arquivos em perguntas com resposta no navegador. Por enquanto, esta página já organiza o estudo e permite seguir a aula inteira sem abrir os arquivos manualmente.