Bug report

At a glance

Why it matters

A developer fixes what they can see. ISTQB defines a defect report as the documentation of a defect's occurrence, nature and status (ISTQB), and the "occurrence" half is the part most reports skip: a one-line complaint with no steps sends the developer hunting for a state they may never reach, and the bug comes back as "cannot reproduce". Mozilla's guidelines call the steps the most important part of any report and ask for a summary that explains the problem rather than a solution (Mozilla). Chromium adds a check that saves everyone a round trip: verify on the latest build before filing, because the bug may already be fixed (Chromium).

What does a bug report include?

• 1. A summary. About ten words that say what is wrong and where: "Pay now stays disabled after a valid card on Safari".
• 2. The starting point. The URL, whether you were signed in, what was in the form or cart, and the viewport or device.
• 3. Steps to reproduce. One action per numbered line, in the order you took them.
• 4. Expected and actual results. What should have happened, then what did, as observed. Theories about the cause go on their own line, marked as a guess.
• 5. The environment. Browser and version, operating system and the build or release you tested, verified current.
• 6. How often. Every time, sometimes with a rough rate, or once.
• 7. Evidence. A screenshot or recording of the actual result, and for a visual bug the element's computed CSS.

Examples

Common mistakes

• A summary that proposes the fix. "Make the button blue" hides the actual problem. Mozilla asks for the problem, not the solution.
• No starting point. "Click Save" means nothing without the page, the account and what was on the form.
• Facts and guesses on one line. "The API must be timing out" is a theory. Mozilla asks reporters to keep speculation apart from what they saw.
• Several bugs in one report. Each one needs its own steps, owner and close, so Mozilla asks for one issue per report.
• Filing against an old build. Chromium asks reporters to verify on the latest version first; a bug already fixed costs everyone a round trip.

Frequently asked questions

What is the difference between a bug report and a defect report?

Nothing in practice. ISTQB defines a defect report as documentation of the occurrence, nature and status of a defect, and lists bug report as its synonym. Teams say bug report; test standards say defect report.

How long should a bug report be?

As long as it takes to reproduce the bug and no longer. Mozilla's guidance is a summary of about ten words, then precise numbered steps with one action per line, the expected result, the actual result and the environment.

Who writes bug reports?

Whoever finds the bug: testers, developers, designers, support staff, clients and users. The format is the same for everyone, and a report that includes the steps, the environment and a screenshot gets fixed regardless of who filed it.

Do I need a screenshot in a bug report?

Yes, whenever the result is visible. Chromium lists screenshots among the things a report should include. The steps let a developer reach the state; the screenshot proves what they should see there, and for a visual bug the element's computed CSS is the fastest route to the fix.

What should a bug report leave out?

Guesses presented as facts, a second bug, and the proposed fix. Mozilla asks for the problem rather than the solution, for speculation on its own line, and for one issue per report, so each can be reproduced, assigned and closed on its own.