TL;DR, Quick Answer
6 min readSteps to reproduce are the numbered actions, starting state and inputs that let a second person trigger the same bug the first person found. A complete set names the preconditions, the exact clicks or inputs in order, the expected result, the actual result and the environment. Skip any one of those and an engineer either cannot reproduce the bug or reproduces a different one, which is why "works on my machine" is a missing precondition, not a mystery.
What are steps to reproduce in a bug report?
A bug report earns the label reproducible when its steps to reproduce list the exact numbered actions, starting state and inputs needed to trigger the failure again. Anyone reading the list, not just the person who found the bug, should be able to follow it and land on the same error. Write the steps as a short script for another person to run, not as a summary of what happened, or attach a session replay so the script writes itself from the recording.
What does a complete steps to reproduce section contain?
A complete section names five things: the preconditions, the numbered actions, the expected result, the actual result and the environment. Missing any one of them turns a reproducible bug into a guess, since an engineer without the starting state has to reconstruct it before they can even attempt the steps. That same detail also decides severity vs priority, since a scorer without a full reproduction guesses at both the damage and the urgency.
| Field | What it answers | Example |
|---|---|---|
| Preconditions | What state must exist before step 1 | Logged in, cart has 2 items, coupon applied |
| Numbered steps | What to click, type or submit, in order | 1. Open checkout 2. Click "Apply gift card" 3. Enter a 20-digit code |
| Expected result | What should happen | Error message: "Invalid code" |
| Actual result | What happens instead | Page goes blank, no error shown |
| Environment | Where it happens | Chrome 128, macOS 15, staging |
Why do preconditions matter before the numbered steps?
Preconditions matter because the same click sequence produces different results depending on the state the user started in. "Click checkout" behaves one way with an empty cart and another with a coupon already applied, so a step list without preconditions gives an engineer the actions but not the starting line. State the account type, the data already in the system and any prior actions taken in the same session before step one.
How should expected versus actual behavior be written?
Expected and actual behavior belong on separate lines, each stating one concrete outcome rather than a feeling about the bug. Write the expected result as what the interface is supposed to show, and the actual result as exactly what appeared instead, including error text, a blank screen or a wrong value. "The page looks broken" reproduces nothing; "expected an 'Invalid code' message, got a blank white page with no console output" gives the engineer a specific target to match.
What environment details belong in a bug report?
Environment details cover the browser and version, operating system, screen size, network conditions and whether the bug happened in production, staging or a local build. A layout bug tied to Safari's flexbox handling or a timing bug tied to a slow connection disappears the moment someone tests it on a different setup, so the environment line is what turns "I can't reproduce this" into "I tested the wrong browser."
Why does works on my machine happen?
"Works on my machine" happens when the reporter and the engineer are silently running different preconditions or environments, not when the bug is fake. A feature flag on for one account and off for another, a stale cache, a different screen width or a browser extension that blocks a script all reproduce the failure for one person and hide it from the next. Treat the phrase as a missing field in the report, and go back to fill in the environment and preconditions instead of closing the ticket. When the flow is long, cutting it down to a minimal reproducible example that still fails on a second machine isolates which precondition is actually doing the work.
How does session replay shortcut writing steps to reproduce?
Session replay shortcuts the write-up because the recording already contains every click, input and page state a manual report would have to describe by hand. Flowsery attaches the replay and steps to reproduce to each issue and bug report automatically when it lands in Slack, Linear or Jira, so an engineer watches the exact sequence instead of trusting a user's memory of what they clicked. Rage clicks and dead clicks mark the moment the user hit the failure, which removes the guesswork about where in the flow to start looking, and tagging @flowsery in the same Slack thread opens a draft pull request once the fix is clear.
Frequently Asked Questions
What makes steps to reproduce good instead of vague?
Good steps to reproduce are numbered, start from a stated precondition, and end with a stated expected result next to the actual result. A vague report describes a feeling ("checkout is broken"); a good one lists five clicks, what should have appeared, and what appeared instead.
What is the difference between steps to reproduce and a bug description?
A bug description explains what went wrong in prose, while steps to reproduce is a script another person can run to see the same failure. A report can have a clear description and still be unreproducible if it skips the numbered actions or the starting state.
Why can't an engineer reproduce a bug that a customer reports?
An engineer usually cannot reproduce a reported bug because the report is missing a precondition or an environment detail, such as an account state, browser version or feature flag that differs between the two setups. The bug is real; the report is incomplete.
What should go in the environment section of a bug report?
The environment section should name the browser and version, operating system, screen size, network conditions and whether the bug occurred in production, staging or local. Any one of these can change whether a bug appears at all.
How many steps should a reproduction have?
A reproduction should have as many numbered steps as there are distinct actions the user took before the failure, no more and no fewer. Combining two actions into one step, or padding the list with steps that do not affect the outcome, makes the report harder to follow, not easier.
Does session replay replace written steps to reproduce?
Session replay replaces the need to write the numbered actions by hand, since the recording shows the exact clicks, inputs and page states in order. The environment and preconditions still get attached automatically with the replay, so the engineer opens one issue instead of asking the reporter for missing details.
Flowsery
Start FREE Trial
Real-time dashboard
Goal tracking
Cookie-free tracking
Why doesn't "the page looks broken" count as a bug report?
"The page looks broken" describes a feeling, not an outcome, so it gives an engineer nothing to match against. A report needs two separate lines: what the interface was expected to show, and exactly what appeared instead, including error text or a blank screen. Compare it to "expected an 'Invalid code' message, got a blank white page with no console output," which points straight at what to check.
How do steps to reproduce affect severity and priority?
A scorer without full reproduction steps has to guess at both the damage a bug causes and how urgently it needs fixing. Preconditions, numbered actions, expected result, actual result and environment together tell a triager what actually breaks and for whom. Skip any of those fields and severity and priority become estimates instead of decisions.
What do rage clicks and dead clicks add to a bug report?
Rage clicks and dead clicks mark the exact moment a user hit the failure inside a session replay. That timestamp removes the guesswork of where in a recorded flow to start looking for the bug. Paired with the automatically attached steps to reproduce, an engineer jumps straight to the failure instead of scrubbing through the whole session.
Which tools does Flowsery attach steps to reproduce to automatically?
Flowsery attaches the session replay and steps to reproduce to each issue automatically when it lands in Slack, Linear or Jira. An engineer then watches the exact sequence of clicks and inputs instead of relying on the reporter's memory of what happened. Tagging @flowsery in the same Slack thread can also open a draft pull request once the fix is clear.
Was This Article Helpful?
Let us know what you think!
See us more often in Google
One click marks Flowsery as a preferred source, so our articles sit higher in your Top Stories, AI Mode, and AI Overviews.
Before you go...
Flowsery
Revenue-first analytics for your website
Track every visitor, source, and conversion in real time. Simple, powerful, and cookie-free.
Real-time dashboard
Goal tracking
Cookie-free tracking
Related Glossary Terms
Two Numbers Hide Behind One Drop-off Rate
Every funnel produces two drop-off rate numbers, one per step and one end to end, and teams quote them interchangeably. A worked table separates them.
The Setup Choices Behind Every Funnel Analysis
Three setup choices decide what funnel analysis reports: step sequencing, the conversion window, and whether the funnel counts users or sessions.
What Autocapture Records Without Any Manual Instrumentation
In product analytics, autocapture records every click, page view and form submit automatically, without a single tracking call written by hand.
The Four Frustration Signals and What Each One Means
The four frustration signals are rage clicks, dead clicks, error clicks and thrashed cursors. Each one fires on a threshold your tool sets, not on a guess.
How Session Replay Works, and What It Cannot See
A session replay rebuilds a visit from DOM mutations and input events, not video. See what it captures, what masking hides, and how it differs from heatmaps.
What the Numbers Say About Average Bounce Rate by Industry
Nine tracked industries return a documented average bounce rate by industry ranging from 35.76% to 48.38%, sourced from Databox data dated September 2024.
Related Articles
Working Through the Average Order Value Formula Step by Step
The average order value formula divides revenue by orders, and a single discount code or return policy can quietly distort every number a team reports.
Reading a Retention Curve Starts With Cohort Analysis
A retention curve only makes sense once cohort analysis groups users by a shared start date, since one average hides the pattern a cohort table reveals.
Where Drop-off Really Happens in a Conversion Funnel
Step conversion and overall conversion answer different questions about a conversion funnel, and the gap between them shows exactly where drop-off happens.