Steps to Reproduce a Bug: How to Write Them

Write steps to reproduce a bug that a developer can follow on the first try: start from a known state, one action per step, exact values, expected versus actual. Plus when numbered steps are the wrong tool.

Good steps to reproduce let a developer who has never seen the bug make it happen on the first try. Start from a known state, write one action per step, use the exact values you used, and finish with what you expected and what happened instead. Keep them as short as the bug allows. Some bugs do not suit numbered steps at all, and for those a plain description of the conditions is more honest and more useful. This post covers both, as a focused companion to the full guide to writing a bug report.

Five rules for good steps

Start from a known state. Say where you begin: logged in or not, which account type, a clean cart or a full one. Step 1 is rarely "Click the button". It is closer to "Log in as a customer with an empty basket".
One action per step. "Add a product and go to checkout" is two steps. Merged steps hide the one where things go wrong.
Use the exact values. "Enter a long name" is not reproducible. "Enter 'Åsa Müller-Jørgensen' as the first name" is. Include the data that triggered the problem: the coupon code, the date range, the file you uploaded.
End with expected and actual. After the last step, write what you expected to happen and what happened instead. Developers use the gap between the two to see what is wrong.
Test your own steps once. Follow them from a fresh start, as written. Many "cannot reproduce" replies come from a step that was assumed and left out.

A bad version and a good one

Bad:

Checkout doesn't work with coupons. Please fix.

Also bad:

1. Go to the site
2. Add something to the cart
3. Use a coupon
4. It breaks

Good:

Environment: Chrome 141, Windows, staging.example.com
Start: logged in as a customer, empty basket

1. Open /products/starter-kit and click Add to basket
2. Open the basket and click Checkout
3. In the Coupon field, enter SAVE10 and click Apply

Expected: the total drops by 10% (from 120.00 to 108.00)
Actual:   the Apply button shows a spinner for several seconds, then the total stays at 120.00 with no message

Frequency: every time, with this coupon. Works with WELCOME5.

The good version is not much longer. It names the starting state, uses real values, separates expected from actual and says how often it happens. The last line is useful on its own: a coupon that works for one code and fails for another points the developer toward the data, not the checkout.

When the steps are not enough

Numbered steps assume the bug depends on what you click. Many bugs depend on something else, and steps alone will not reproduce them:

Data. The bug appears only for one account, one record or one value. Include its ID or describe it: "customer with an expired card on file".
Environment. A specific browser, device, screen size, language or time zone. Say which, and say if you tried another.
Timing. A slow connection, a double click, a request that returned after the user had moved on.
State left behind. Something you did earlier in the session, such as a half-filled form or an expired login, that changed the result.

When a bug depends on these, a numbered list reads as complete but is not. Add a line headed "Conditions" under the steps and list what else was true. The error text and the failed request matter too, which is why what developers need in a bug report goes beyond the steps.

When not to write steps

Numbered steps are the wrong tool when:

The bug is visible on one page. A misaligned logo or a wrong label needs the address, a marked-up screenshot and one sentence. Five steps to get there add nothing.
Everyone can see it. If every user hits it on page load, "open the home page" is the whole reproduction.
You are guessing. If you do not know what triggered it, do not invent steps that look tidy. A wrong recipe sends the developer down the wrong road.
The steps are very long. If it takes 25 steps to reach the bug, say where you are in the process and what you did right before, and offer a recording or a walkthrough call.

If you cannot make it happen again

Intermittent bugs are reported too, and they should be. Be plain about it instead of dressing it up as a recipe:

Say that you could not reproduce it, and how many times you tried.
Say what you were doing when it happened, and what you had done in the minutes before.
Note the time it happened, the account and the page address, so a developer can look in the logs.
Attach whatever evidence you captured at the moment: the error text, a screenshot, a recording.

"Happened once at 14:32 on account 4821, after about ten minutes on the invoices page; could not repeat in three tries" is more useful than five invented steps. The developer can search the logs for 14:32. They cannot search the logs for something you made up. For more on why bugs go missing between reporter and developer, see why "cannot reproduce" happens.

Letting the tool write them

Writing steps by hand is the part testers and clients skip, because they cannot remember exactly what they clicked. A tool that watches the session can write them from what actually happened. SnagRelay builds the steps from the session, so a tester who clicks Report does not type them, and the console errors and failing requests come attached. A tester can still add context in their own words, and should: the steps say what they did, but only they know what they expected. See bug reporting without DevTools for the other pieces of context that arrive automatically.

FAQ

How many steps should a bug report have?

As few as it takes to reproduce the bug from a known starting point. Many bugs need only three to eight. If you need more than about ten, check whether you can start closer to the problem, and say what state you started from.

What is the difference between expected and actual results?

Expected is what the system should have done, and actual is what it did. Writing both makes the problem explicit, because a developer cannot tell whether a behaviour is a bug unless they know what you thought would happen.

What do I write if I cannot reproduce the bug?

Say so. Report what you were doing when it happened, the time, the account and the page, and attach any evidence from the moment. Do not guess at steps; an honest "happened once" gives developers something to search for.

Should steps to reproduce be numbered?

Yes, when the order of actions matters, because numbers make the sequence clear and let a developer say "it fails at step 3". For a single-page visual issue, a sentence is enough.

Steps to Reproduce: How to Write Them, and When Not To