You already know the report structure: title, steps, expected and actual results. But correctly filled fields don't yet make a report good. There's a saying that a well-written bug report is half the solution for the developer: the same problem can be described so that a couple of lines of code remain to fix — or so that the author themselves won't understand it tomorrow. This article is about what separates a report that gets fixed from a report that gets bounced back.

Understand first, write second

Everything starts not with the form fields but with understanding what's happening. Until you clearly understand what broke, it's too early to write the report: you'll describe the outward manifestation, not the essence.

The working formula is to state the problem as three answers: what you did, what you got, what you expected to get. "What you did" becomes the steps to reproduce, "what you got" — the actual result, "what you expected" — the expected one. The formula has a bonus: it shows in advance whether this is a defect at all. If for "what you expected" you can point to neither a requirement nor common sense — perhaps the application is behaving correctly.

Then comes the filling order: start with the detailed description, not the title. While you spell out the details, more of them surface and a compact wording emerges — the title is easiest to write at the very end. And always reread the finished report: logical gaps and missing steps are found precisely on rereading.

Detail level: a report plays by different rules than a case

In the article on test case quality we sought a balance between specificity and generality. In a bug report the balance shifts: specificity wins. The reason is simple: one missing small detail can make the defect unreproducible. If you have the slightest doubt whether a detail matters — assume it does. A developer won't reproduce "a file of an allowed format where Russian text appears in different encodings"; they will reproduce "an HTML file of 100 KB to 1 MB with text in UTF-8 (10 lines) and WIN-1251 (20 lines)" on the first try.

Specificity doesn't mean verbosity, though:

  • Don't spell out what one phrase replaces. Four steps "specify the first parameter… the second… the third… launch" collapse into "launch the application with all three correct parameters."
  • Don't start "from the creation of the world." Instead of steps "launch the application, wait 30 minutes," write a precondition: "the application has been running for over 30 minutes" — and keep the one step that triggers the bug.
  • Remove details that don't affect the defect. If search doesn't find mp3 files, it doesn't matter that the file is named song1.mp3 and sits on drive J:. How do you tell what matters? By investigation: understand the pattern of the behavior, and the necessary level of detail becomes obvious.

Real examples of details without which a defect couldn't be reproduced for weeks: two or more consecutive spaces in a folder path; a file larger than the memory available to the application; a user whose role was never explicitly set in the database. Noticing such things is exactly what investigating the cause — rather than the manifestation — means.

One defect — one report

Two unshakable rules:

  • Each report describes exactly one defect. If one defect shows up in several places, the manifestations are listed in the detailed description of a single report. If a report contains two defects and one is fixed while the other isn't — what status do you move the report to? Unknown.
  • A new defect means a new report. Never describe a new problem by reopening an old closed report: history is lost, metrics break, chaos follows. That's exactly why on many projects only a limited circle of people may reopen reports.

Duplicates: search before, don't apologize after

When there are many testers (or memory is short), the same defect gets described twice. The defenses:

  • Search before filing. A keyword search in the tracker is a mandatory step before creating a report.
  • Write informative titles — search runs on them first. A dozen reports titled "Button doesn't work" turn every next search into manual sifting.
  • Include the application's message text in the description — an exact error text finds the duplicate even when everything else is described too generally.
  • Found extra information about an already-filed bug — add it to the existing report instead of creating a new one.

Typical mistakes

Formatting mistakes:

  • Riddle titles: "Unexpected interruption," "19 items found," "Red font in the application." What's the problem? Where? Under what conditions? Unclear.
  • Ignoring quotation marks: "the record disappears on mouse hover" is scary until you learn that what disappears is the field named "Record." Quotes signal an element's proper name.
  • A full-screen screenshot with nothing marked. Circle the problem area — comprehension speeds up several times over. And attach the file itself if the bug involves a file: a "file is processed incorrectly" report without the file is useless.
  • Putting it off "for later." You found five bugs and decided to file them in the evening — by evening the details (and sometimes the bugs themselves) are forgotten. File immediately.

Logical mistakes — more dangerous:

  • Invented defects. Nowhere do the requirements say the application should do this — yet a report is filed because it doesn't. The expected result comes from requirements or common sense, not from imagination.
  • Jargon and criticism instead of description. "The charts hooked up lousily" or "who even wrote this?!" — a report describes a problem with the application, not the qualities of colleagues.
  • Focusing on trifles at the expense of the main thing. The textbook case: a tester found a crash with data loss but filed it as a cosmetic defect — the dying error message contained a typo. Always ask yourself: how does this affect the user?
  • Understated severity. Thoroughly investigate the defect's most dangerous consequences and defend your assessment with arguments — a severely understated report can wait months for its turn.
  • Accepting "sometimes" reproducibility. "Sometimes" means the real cause hasn't been found: everyone — you and the developer — will have to work with such a defect on faith. Keep looking for the pattern: extra tests, similar functionality, consulting colleagues. The share of "unreproducible" defects can be brought close to zero.

Where this applies

The fate of your bug is decided by report quality. A good report gets fixed in minutes and without questions; a bad one comes back with "cannot reproduce" and "not a bug" resolutions — and everyone loses time. Reports are also how you're judged: the whole team reads them, every day.

Where beginners stumble:

  • They write the report without understanding the essence. The outward manifestation is described ("random files are sometimes processed"), not the pattern — reproduction is impossible.
  • They carry the test-case habit into reports — leaving "meaningful freedom" in the steps. In a report, freedom is harmful: when in doubt, be specific.
  • They file reports against functionality not yet declared ready for testing — stating that something doesn't work which wasn't supposed to work (yet!).

What to learn next. Where the report goes after creation and what statuses it passes through — in the bug lifecycle article; how to assess how serious and urgent a defect is — in the severity and priority article.