Reproduction steps are the part of a bug report that lets somebody else make the bug happen. "Steps to reproduce", "repro steps" and "how to reproduce" all mean the same thing: a sequence a stranger can follow, from a state they can reach, that ends in the behaviour you saw.
They matter more than any other part of the report. A developer who can reproduce a bug is most of the way to fixing it. One who cannot is guessing, and will usually guess that the steps are wrong.
The short version
- Start from a state the reader can reach. A fresh login, a named test account, a URL.
- One action per step, numbered, in the order you did them.
- Name the data. Which record, which file, how big.
- End with what happened, and what you expected instead.
- Say how reliably the steps produce it.
Start where the reader is
The most common failure in reproduction steps is not vagueness. It is starting halfway through. By the time you noticed the bug you had built up a state: a project created last week, a filter applied earlier, a setting changed once and forgotten. Your steps begin after all of that. The reader's begin before it.
- Open the report.
- Click Export.
- Nothing happens.
- Log in as the QA account.
- Reports, then All Activity.
- Set the range to 1 May to 29 July; the table shows about 4,300 rows.
- Click Export, then CSV.
- The download contains exactly 1,000 rows, with no error and no warning.
The test for a first step: could somebody who has never seen your screen do it? If it says "the report", "your project" or "the usual settings", it cannot be the first step.
One action per step
Each step is one thing the reader does, written as an instruction rather than a description. "Go to settings, change the timezone, save and reload" is four steps, and if the bug depends on the order, collapsing them hides it.
Number them. A developer who can reply "it goes wrong for me at step 3" has told you something precise. "Cannot reproduce" tells you nothing.
Name the data
"A large file" is an opinion. "A 40 MB PDF" is a fact, and the number is frequently the entire bug. Wherever a step involves a choice of input, say which input: the record ID, the filename, the exact text you typed, the option you picked from the list.
If the input is something you cannot share, describe its shape instead: how many rows, what characters it contains, whether the name is unusual.
End with the result, both halves
The last step is not an action. It is what you saw, followed by what you expected to see. Put both, because the gap between them is the bug, and a reader who has only one half will fill in the other from their own assumptions.
Be literal about what you saw. "It fails" covers an error message, a blank screen, a spinner that never stops, a success message with the wrong result, and silence. Paste error text rather than describing it. If there was no error, say so: "no error, no warning" tells the developer the software did not know it had failed.
Say how reliable the steps are
Follow your own steps once more before you send them, then report what happened: "five out of five", "about one attempt in three", "once, and not since". An intermittent bug is still worth reporting, but it is approached differently, and knowing it is intermittent stops the developer concluding the steps are wrong when their first attempt passes.
Add the environment in one line: browser, operating system, the version of the software if you can see it, and anything unusual about the account or the connection. Only one of those will turn out to matter, and you do not know which, so a line covering all of them is cheaper than a round trip.
When you cannot reproduce it yourself
Sometimes there are no steps, because it happened once and you were not paying attention until it was over. Do not invent steps. Send a different kind of report:
- When, as precisely as you can. A timestamp turns the report into a log search, which is often better than reproduction.
- Who and what: the account, the record, the request ID if one was shown.
- What was different: first time using it, a bigger input than usual, just after an update, a poor connection.
- What you saw, in the same literal detail as above.
That is not a substitute for steps. It is an honest report, and it is often enough to find the bug from the other end.
What steps are not
Not a diagnosis. "Clear the cache and it works" is useful, but it goes after the steps, labelled as a workaround, not in place of them.
Not a screenshot. A screenshot shows the end state. It does not show how you got there, and it cannot be searched. Attach one if it helps, but write the steps too.
Not a video, unless it is short and the steps are also written. Nobody scrubs through four minutes of screen recording to find the click that mattered.
A complete example
- Log in as qa-finance on staging.
- Reports, then All Activity.
- Set the date range to 1 May to 29 July; the table shows about 4,300 rows.
- Click Export and choose CSV.
Result: a file of exactly 1,000 rows downloads, with no error and no warning. Expected all 4,300.
Reproduced 3 of 3 attempts from a fresh login, in Chrome and Safari on macOS. The same range exported correctly on 14 July.
The example is not long. Good steps are short because each one is precise, and precision is what makes them short.