Bug reporting
Steps to reproduce
Steps to reproduce are the exact, numbered actions that make a bug appear again: where to start, what to do, what you expected and what happened instead.
Mozilla's bug writing guidelines call them the most important part of any bug report, because a bug a developer cannot see is a bug they cannot fix.
At a glance
| Starting point | The URL, the account state and the viewport, so the first step lands in the same place |
| Steps | One action per numbered line, with what you were trying to do when the action alone is ambiguous (Mozilla) |
| Expected vs. actual | Two separate lines, with facts kept apart from guesses about the cause (Mozilla) |
| Reproducibility | Every time, sometimes, or once (Mozilla) |
| Environment | Browser and version, operating system, build, and the page URL (Chromium) |
| Evidence | A screenshot or recording of the actual result, and the element's computed CSS for a visual bug |
| Captured with | OverlayQA Visual Bug Capture |
Why it matters
Mozilla's bug writing guidelines call steps to reproduce the most important part of any bug report (Mozilla). A developer fixes what they can see. A report that says "the checkout is broken" sends them hunting for a state they may never reach, and the bug comes back as "cannot reproduce". Chromium's guidelines ask for the same things in the same order: verify on the latest build, give a one-line description, then detailed steps, then the expected behavior, and include the URL (Chromium).
How do you write steps to reproduce?
- 1. Start from a known state. Name the URL, whether you were signed in, what was in the cart or the form, and the viewport or device.
- 2. Number each action. One action per line: click, type, scroll, resize. Say what you meant to do when the click alone could mean two things.
- 3. Write the expected result. What should have happened, in one sentence.
- 4. Write the actual result. What happened instead, as observed. Keep theories about the cause on a separate line, marked as a guess.
- 5. Say how often. Every time, sometimes with a rough rate, or once.
- 6. Attach the evidence. A screenshot or recording of step 4, and for a visual bug the element's computed CSS.
- 7. One bug per report. A second bug gets a second report, with its own steps.
Examples
| A report that bounces | A report that gets fixed |
|---|---|
| "Pay now does nothing on mobile." | 1. Open /checkout/ in Safari on an iPhone (390 px wide), signed in, with one item in the cart. 2. Tap Pay now. Expected: the payment sheet opens. Actual: nothing opens and the button turns gray. Happens every time (3 of 3). Screenshot attached. |
| "The hero text is cut off sometimes." | 1. Open the home page at 1280 px wide in Chrome on macOS. 2. Press Cmd and Plus twice, to 125% zoom. Expected: the headline wraps to a second line. Actual: the second line is clipped by the hero image. Reproduces every time at 125%, never at 100% or 150%. |
Common mistakes
- Starting mid-flow. "Click Save" means nothing without the page, the account and what was on the form.
- Describing the symptom instead of the actions. "The button is broken" is a result, not a step.
- Mixing cause with observation. "The API must be timing out" is a guess. Mozilla asks for facts and speculation on separate lines.
- Several bugs in one report. Mozilla asks for one issue per report, so each can be reproduced, assigned and closed on its own.
- Leaving out the version. Chromium asks reporters to verify on the latest build first. A bug already fixed upstream costs everyone a round trip.
Frequently asked questions
What is the difference between steps to reproduce and expected results?
The steps are the actions that lead to the bug. The expected result is what should have happened after the last step, and the actual result is what did. Mozilla asks for all three, with facts kept apart from speculation about the cause.
How many steps should a bug report have?
As many as it takes from a known starting point, with one action per step. Mozilla's guidance is to describe the method of interacting and, where it matters, the intent of each step, so a developer can follow it without guessing.
What if the bug does not happen every time?
Say so. Mozilla asks reporters to state whether a bug reproduces at will, occasionally or not at all. A rough rate, such as 2 of 5 tries, plus what you varied between tries, is more useful than leaving the field blank.
Do I still need a screenshot if the steps are complete?
Yes. The steps let a developer reach the state; the screenshot proves the actual result and carries the details words miss, such as exact spacing, colors and text. For a visual bug, the element's computed CSS is the fastest route to the fix.
Sources: Mozilla, Bug Writing Guidelines, Chromium, Bug Reporting Guidelines.
Last updated October 22, 2026