How to write bug reports developers can use
Most bugs are not hard to fix. They are hard to see, because the report that describes them leaves out the one detail a developer needs.
Why bug reports fail
A typical report is a screenshot in a chat thread and a line like “checkout is broken.” The person who found the bug knows exactly what happened. The developer reading it does not.
So the questions start. Which page? Which browser? Were you logged in? What did you click first? Each answer takes time, and by the time it arrives, the tester may not remember.
The fix is not more effort from developers. It is a better report the first time.
What every report needs
A report is useful when someone else can follow it and see the same bug. That takes these things:
- A clear title. Say what broke and where. “Cart total ignores discount code on checkout page” beats “Cart bug.”
- Steps to reproduce. Number them. Start from a known place, such as a page URL or a fresh login.
- Expected and actual result. One line each. This tells the developer what “fixed” looks like.
- Environment. Browser, version, operating system, screen size, and the exact URL.
- Evidence. A screenshot or a short recording that shows the moment it goes wrong.
If you only add one thing to your current process, add the steps. A bug with good steps usually gets fixed. A bug without them often sits in the queue.
The details that are easy to miss
Many bugs come from things the tester cannot see on screen.
A button looks dead, but the real cause is a failed request behind it. A page shows old data because an API call returned an error. A form freezes because a script threw an exception.
These clues live in the browser’s developer tools:
- Console logs show script errors and warnings.
- Network requests show which calls failed, their status codes and how long they took.
You do not need to be a developer to collect them. Open the developer tools before you start testing, keep the Console and Network tabs open, and copy anything red into the report. Developers will thank you for it.
Write steps someone else can follow
Good steps are short and specific. Each step is one action.
Write “Click Add to cart on the first product” instead of “add something.” Write the value you typed, not “enter some text.” If the bug only happens with certain data, say which data.
Then test your own steps. Start again from step one and follow them exactly. If you cannot reproduce the bug from your own report, the developer will not either.
A few more habits help:
- Report one bug per report. Two bugs in one ticket slow both down.
- Say how often it happens. Every time, or once in ten tries, is a useful signal.
- Mark what you already ruled out, such as a cleared cache or a second browser.
Share it where the work happens
A report that sits in a chat thread gets lost. Put it where your team tracks work, such as your issue tracker, and link to it from the chat.
Think about who will read it. A product manager needs a clear title and a short summary. A developer needs the steps and the technical details. A good report serves both, with the summary on top and the details below.
Be careful with what you share outside the team. Logs and requests can contain private data, so check them before you send a report to a client or a vendor.
How Stepix helps
Collecting all of this by hand takes time, which is why many reports skip it. Stepix does the collecting for you.
Stepix is a Chrome extension. You capture a screenshot or record a video of up to 5 minutes. Stepix builds the report with the page URL, environment, console logs and network requests attached. Track a session, and it lists each click as a numbered step with a screenshot.
You can draw and write on screenshots before you save. You can set status, severity and priority, and push a report to GitHub, GitLab or Jira as an issue. To share outside your tracker, send a read-only link and choose which technical details viewers can see.
The advice above works with any tool. Stepix makes it the default. See how Stepix works.
