The Great Bug Report

A bug you found but reported badly might as well not exist. It bounces back "cannot reproduce," waits three days for clarification, or gets fixed wrong because the developer guessed at what you meant. The bug report is a QA engineer's most-read piece of writing — read by developers, leads, product, sometimes support — and writing one a developer can act on in a single read is a completely learnable craft. This page teaches it on the book's signature bug, written up in full.

Think of a police report. Time, place, what happened, evidence attached — because the detective wasn't there, and the report's whole job is to put them at the scene. Your developer wasn't at your desk either. The report is the scene, portable.

One Report, One Bug

The zeroth rule, before any anatomy: a report is a self-contained case file for one problem. Two bugs in one ticket means one gets fixed, the ticket gets closed, and the second bug quietly evaporates — the mega-case failure from Chapter 5, wearing tracker clothes. Found three problems in one afternoon? Three tickets, cross-linked if related. (You already know the atomicity logic; it transfers wholesale.)

The Anatomy

Six fields make a report a reproduction machine. The title — the headline: symptom, where, and condition, findable and specific. The environment and build — Chapter 2's two questions, answered up front, because they're the first thing any developer checks. The steps to reproduce — numbered, minimal, from a known starting state. The expected result — with its source cited: the story, the criterion, the convention. The actual result — what happened instead, factually. And the evidence — screenshot, recording, the exact data used. Here is FW-312, the real write-up:

Steps That Reproduce — the Discipline

The steps field has a quiet quality bar: minimal, and re-run before submitting. Minimal means every step earns its place — if the bug reproduces without step 3, step 3 goes; the shortest path to the failure is the fastest path to the fix. Re-run means exactly that: before you click submit, follow your own steps, literally, from the top. Half the "cannot reproduce" ping-pong in the world comes from reports whose steps skip something the reporter did unconsciously — the login, the time zone, the leftover state from a previous test. Your own steps, followed cold, are the test of the report.

And when the bug is intermittent — reproducing sometimes, on no clear conditions? Report it anyway, honestly: "reproduces roughly 1 in 5 attempts; conditions not yet isolated; recording of one occurrence attached." Frequency, what you've ruled out, evidence of one occurrence. Intermittence is information — it whispers about timing, caching, or race conditions (your grey-box instincts should tingle) — and an honest 1-in-5 report beats a silent wait for certainty that may never come.

Expected vs Actual: the Payload

These two lines are what make the document a bug report instead of a complaint. Notice FW-312's expected result cites its source — story FW-201's criterion. That citation does two jobs: it proves the gap is real (not your taste), and it pre-answers the "works as designed?" question from last topic. When the source is a reasonable expectation instead of a document, say so explicitly: "expected: back button returns to search results, per standard browser behavior." An expected result with a named source is an argument already won.

Evidence: Show, Don't Tell

The FW-312 screenshot — picker showing Nov 13, summary showing Nov 14, side by side — communicates the entire bug in two seconds. Three paragraphs of prose can't compete, and don't have to: attach, then reference. Screenshots for states, recordings for flows (the whole reproduction, narrated by the clicks themselves), exact data for anything involving inputs. One habit upgrade from Chapter 8 will make your evidence professional-grade — wait for it — but even now: every report ships with its proof. A claim with evidence gets fixed; a claim without evidence gets discussed.

The Rookie Version, for Contrast

The same bug, as it gets filed every day somewhere: title "booking dates are wrong sometimes :(" — no environment, no build, steps "make a booking and look at the dates," expected "dates should be correct," no evidence. Watch the ping-pong this buys: Omar tries it (UTC−5 machine), can't reproduce, bounces it back. You clarify "it happened on my laptop." He asks which build. Two days pass; the bug is now angry at both of you, and it still isn't diagnosed — because the report made the developer do the investigation the reporter had already done and thrown away. Every field in the anatomy exists to delete one round of that ping-pong. The great report costs ten extra minutes and saves two days; that's the trade, every time.