Docs

How to write steps to reproduce a bug

Why reproduction steps are the part that goes wrong, what a usable one looks like, and how to stop asking for them.

Ask any engineer what ruins a bug report and the answer is the same: the steps. In one survey of defect reports, over 95% of respondents named incomplete reproduction steps as the biggest problem — ahead of missing screenshots, wrong severity or bad titles.

It is worth being precise about why, because the usual fix — writing a better template — does not address it.

The steps are a reconstruction, not a recording

Somebody who hits a bug is not observing themselves. They are trying to do something, it fails, and then they turn around and try to remember how they got there. What they write down is what they intended to do, which is a tidied-up version of what actually happened.

That is why "I clicked Save and it broke" so often turns out to mean the person clicked Save, got a validation error, edited a field, clicked Save again, and the second one failed. The first click never makes it into the report, and it is usually the one that matters.

What a usable set of steps has

If you are writing them yourself, four things separate a report an engineer can act on from one that comes back with questions.

  1. The starting state, not just the action. "From a logged-out session, on the pricing page" is worth more than three steps that assume where you were.
  2. One problem per report. Three bugs in one ticket become one ticket that is never fully closed.
  3. What you expected, next to what happened. Without the first half, the reader has to guess whether it is a bug or a preference.
  4. Specifics instead of adverbs. "The page takes 8–10 seconds" is testable. "The page is slow" is an opinion.

The part you should stop asking for

Some of it should never have been a question in the first place. Browser, operating system, viewport, the exact URL, whether an error was thrown — none of that is something a person should be recalling, and asking for it is how you end up with "Chrome, I think, on my laptop".

That half is mechanical, and mechanical things belong to the software.

What is left for the human

Automating the trail does not make the report write itself. It changes what you are asking the person for, from evidence to intent — the one thing they actually have and your instrumentation never will.

So the form gets shorter, and the remaining question gets better:

What were you trying to do, and what did you expect to happen instead?

That is a question a non-technical customer can answer well in one sentence. "How do I reproduce this in Chrome 131 on macOS" is not, and never was.