How to Write a Bug Report a Developer Can Act On
Part 8 of the Software Testing Course: the anatomy of a bug report that gets fixed fast — clear title, exact reproduction, expected vs actual, and evidence.
A bug report has one job: get the bug fixed with the least back-and-forth. Almost all the friction in fixing bugs — the "can't reproduce," the "works for me," the three comment round-trips — comes from the report not containing what the developer needs to start.
The anatomy of a good report
- Title. Specific and searchable. "Checkout fails with a valid card when the billing address contains an apostrophe" beats "Checkout broken." A good title lets someone find the duplicate before filing it again, and tells a triager the severity without opening the report.
- Environment. Build number or commit SHA, browser and version, OS, the user's role, and which environment (local, staging, production). "Latest" is not a version.
- Steps to reproduce. Numbered, exact, and starting from a known state — "log in as a fresh user with no projects," not "from the dashboard." Include the specific data you used: the actual card number from the test set, the actual text you typed, not "some input."
- Expected result. What should have happened, according to the spec or reasonable behaviour.
- Actual result. What happened instead, verbatim. Paste the exact error text and the exact error code. "It showed an error about a token" costs a round-trip;
Error: refresh token expired (401)does not. - Evidence. A screenshot at minimum. A short screen recording for anything involving timing or animation. Console output and the failing network request (method, URL, status, response body) for anything that looks server-side.
- Severity and priority. Your read on impact and on urgency, kept as two separate judgements — a crash in an unreleased admin tool is high severity, low priority.
What makes reports fail
- "Sometimes it doesn't work." If it's intermittent, quantify it: "about 1 in 4 attempts," and note what was different the times it failed (slow network, second tab open, right after a deploy). An intermittent bug with no pattern is nearly unactionable.
- Missing the starting state. The most common cause of "cannot reproduce." The developer's account isn't in the state yours was — you had a pending invitation, an expired trial, a specific feature flag — and nothing in the report said so.
- Paraphrased errors. Retyping an error message from memory drops the one detail that would have pointed at the cause.
- Multiple bugs in one report. One report, one bug. If you found three things, file three reports — otherwise one gets fixed and the report gets closed with the other two still live.
- Conclusions instead of observations. Report what you saw, not your theory of the cause. "The API returns 500" is an observation. "The database connection is leaking" is a guess that sends the developer down a specific path — fine if you're confident and you label it as a hypothesis, misleading otherwise.
- A wall of unnumbered prose. The developer has to reverse-engineer the steps. Number them.
Reproduce it before you file it
Retrace your own steps once, from a clean state, before you submit. This single habit eliminates roughly half of all "cannot reproduce" responses — because half the time the reporter couldn't reproduce it either, they just didn't check. If it doesn't reproduce on a second try, that's important information: say so, and describe what was different the first time.
Evidence, generated for you
Writing all of this by hand for every bug is real work, which is why bug reports are so often thin. This is one place autonomous testing helps directly: every finding an autonomous run produces already includes a screenshot of the moment it broke and the exact sequence of steps that led there, from a known starting state. The reproduction, the environment, and the evidence are captured automatically — your job shrinks to confirming it's real, setting severity and priority, and routing it. The autonomous testing guide covers how findings are structured.
The takeaway
A good bug report is a specific, searchable title; an exact reproduction from a known starting state, with real data; expected versus actual with verbatim error text; and evidence. Reproduce before filing. One bug per report. Observations, not conclusions. Part 9 covers assembling the bugs you've fixed into a regression suite that stays useful.