A good bug report tells the person fixing it three things: what you expected to happen, what happened instead, and the exact steps that make it happen again. Everything else, screenshots, error text, your device and browser, exists to support that third part. Without steps to reproduce, a bug report is a description of a feeling, not a bug.
If you want the fields rather than the reasoning, there are copy-paste versions in a bug report template you can copy.
This page is one part of a larger guide. For the whole subject in one place, see feature request tools.
What does a good bug report actually contain?
Six things, in order of how much they matter.
- A specific title. "Export button doesn't work" tells nobody anything. "Export to CSV fails on the second attempt after switching tabs" tells the reader where to start.
- What you expected. State the outcome you were trying to reach.
- What happened instead. State the actual outcome, not your theory about the cause.
- Steps to reproduce. A numbered sequence, starting from a known point, ending at the failure.
- Whether it happens every time. Always, sometimes, or once.
- Environment. Device, browser or app version, operating system. Whatever the software runs on.
Everything past that, a screenshot, a video, a console error, is evidence for the steps above it. It is not a substitute for them.
One should be able to tell exactly what a bug is about just by reading the summary.
WebKit, Bug Report Guidelines
Why does each part matter to the person fixing it?
Fixing a bug is finding the smallest set of conditions that makes it happen, then working out why those conditions break the code. A developer cannot do either of those things without first making the bug happen in front of them. That is the whole job of a bug report: get the reader from "I don't see it" to "there it is" as fast as possible.
The title matters because it decides whether the report gets read at all, and whether it gets grouped with the right existing issue. Expected versus actual matters because it separates the bug from an opinion: "the button should be blue" is a design request, "the button is invisible" is a bug, and the two sentences look identical until you write them as expected versus actual. Steps to reproduce matter more than anything else on the list, because they are the only part of the report the developer can actually run. Environment matters because a huge share of bugs only happen on one browser, one screen size, or one version, and without it the developer is debugging blind.
What's the difference between a description and a reproduction?
A description says the app crashes sometimes. A reproduction says: open the settings page, change the theme, then click save twice quickly, and it crashes every time. The first sentence is true and useless. The second sentence is something a developer can run on their own machine, watch fail, and fix.
The test for whether you have written a reproduction rather than a description is simple: could a stranger with no other context follow your steps and land on the same failure? If the steps assume knowledge the reader doesn't have, or skip a step because it felt obvious, they are not a reproduction yet.
A bug report template you can copy
This covers the six parts above in an order that is easy to fill in under pressure.
Title: [one line, specific enough to search for later]
What I expected to happen:
What happened instead:
Steps to reproduce:
1.
2.
3.
Does it happen every time, or only sometimes?
Device, browser and version (or app version):
Screenshot, video, or error message, if you have one:Leave a field blank rather than guessing. A blank field is honest. A guessed answer sends the reader down the wrong path.
What do you do when you can't reproduce it?
Some bugs only happen once, or only under conditions you can't identify. That does not make the report worthless, it changes what goes in it. Replace "steps to reproduce" with as much of the surrounding context as you can remember: what you had just done, what else was open, roughly what time it happened, and the exact wording of any error message on screen. A timestamp is more useful than it looks, because it lets the person fixing it check logs from that moment even when nothing else lines up.
Say plainly that you couldn't reproduce it. A report that admits "this only happened once and I'm not sure how" is more useful than one that invents a confident set of steps that turn out to be wrong, because the developer will spend real time trying to follow steps that were never true.
How do you write one as a non-technical customer?
You do not need to know any technical terms to write a good bug report. You need to describe what you clicked and what you saw, in the order it happened, as plainly as you would tell a friend.
Write down what you were trying to do, not what you think caused the problem. "I tried to download my invoice and got a blank page" is more useful than "I think your download function is broken", because the first sentence is something you actually observed and the second is a guess dressed up as a fact.
A screenshot is worth more than a paragraph of explanation, so take one the moment something looks wrong rather than trying to describe it afterwards from memory. If the same thing happens again, note that too: "every time" and "just this once" change what the person reading it does next.
One payment, no subscription, unlimited products.
What should a bug report form actually ask for?
If you are the one building the form rather than filling it in, the job is to make the good version of a report the easy version to submit. That means asking for the six parts above directly, as separate fields, rather than one open text box labelled "describe your issue".
Make the reproduction field impossible to skip past without noticing: label it "steps to reproduce", not "details", and give it three numbered lines rather than a blank paragraph. Capture environment automatically wherever you can, browser and operating system are visible to the page without asking, so don't spend a customer's patience on a question the software already knows the answer to. Keep everything else optional. A short form that gets submitted beats a thorough one that gets abandoned halfway through.
A good form is doing the same job this article is: getting the useful version of the report instead of the vague one, from someone who did not want to write either.
Frequently asked questions
What's the single most important part of a bug report?
Steps to reproduce. Everything else in a report helps the reader understand context, but only the reproduction steps let them actually see the bug happen. A report with perfect steps and nothing else is more useful than a long report with vague or missing steps.
Should I always include a screenshot?
Whenever you can, yes. A screenshot removes any ambiguity about what you actually saw, and it often shows details you wouldn't think to describe, like an error code in small text or a layout that's subtly wrong rather than obviously broken. It doesn't replace steps to reproduce, it supports them.
How long should a bug report be?
As short as it can be while still including the six core parts. Length isn't the goal, completeness is. A five-line report with clear steps beats a long paragraph that never states what you expected versus what happened.
What if a customer's report has no steps to reproduce?
Ask one follow-up question rather than guessing: what were you doing right before it happened, and does it happen every time? Most missing-steps reports are recoverable with a single reply, because the customer usually remembers more detail than they thought to include the first time.
Does the bug's severity need to be in the report?
It helps but isn't required. A note like "this blocks me from finishing checkout" versus "this is a minor visual glitch" helps whoever triages reports decide what to look at first. If you're not sure how serious it is, describe the impact on what you were trying to do and let the reader judge.