How to write a good bug report, with a template
A good bug report lets a developer reproduce the problem without asking a single question. This guide explains what to include, gives you a template to copy, and shows the mistakes that make bugs hard to fix.
What makes a bug report good?
A good bug report is specific, reproducible and complete. It describes one problem, explains how to make it happen, says what was expected instead, and includes the environment in which it happened. A developer who reads it can open the page and see the bug within a minute.
The eight parts of a good bug report
- Title. A short summary of what is wrong and where. "Checkout - Pay button does nothing on mobile" is better than "Bug in checkout".
- Page address. The exact URL where the problem happens.
- Steps to reproduce. Numbered steps from a known starting point.
- Expected result. What should have happened.
- Actual result. What happened instead, with the exact error message if there is one.
- Environment. Browser and version, operating system, device, screen or window size, logged in or not, and the user role.
- Evidence. A screenshot with the problem marked, or a short screen recording for problems with behaviour.
- Technical details. Console errors and failed network requests, if you can get them.
Add a priority if your team uses one, for example critical (blocks a main function, no workaround), high, normal or low.
Bug report template
Copy this template into your issue tracker, e-mail or chat.
Title: [Area] - [what is wrong]
Page: https://
Steps to reproduce:
1.
2.
3.
Expected result:
Actual result:
Environment: [browser + version], [operating system], [device], [window size]
Logged in as: [role or "not logged in"]
Evidence: [screenshot / recording]
Console errors / failed requests: [if available]
Priority: [critical / high / normal / low]
Example
Title: Product page - price shows "12.9" without the euro sign
Page: https://shop.example/coffee/autumn-roast
Steps to reproduce:
1. Open the product page
2. Choose the 250 g variant
Expected result: the price shows "€12.90"
Actual result: the price shows "12.9"
Environment: Chrome 131, macOS 15, 1440 x 900 window
Logged in as: not logged in
Evidence: screenshot attached
Console errors: none
Priority: high (visible to every customer)
Common mistakes
- Several problems in one report. They get fixed, tested and closed at different times; report them separately.
- No steps. "It doesn't work" cannot be reproduced. Start from a known page and list every click.
- Missing environment. Many layout bugs only happen at one window size or in one browser.
- Screenshots without context. Mark the problem and include the address bar or the page address.
- Opinions as facts. "The blue is ugly" is a change request, not a bug. Say what you would like instead.
Let a tool capture the details
Collecting the environment and console errors by hand is tedious and easy to forget. A visual bug reporting tool captures them automatically. With mumus the reporter clicks on the broken element and writes the title, steps and expected result; the screenshot, page address, browser, window size, console errors and failed requests are added automatically.
Frequently asked questions
What should a bug report include?
A clear title, the page address, numbered steps to reproduce, the expected and the actual result, the environment (browser, operating system, device, window size, user role), a screenshot or recording, and console errors or failed network requests if available.
How do you write steps to reproduce a bug?
Start from a known state, such as a page address and whether you are logged in, then list every action as a numbered step until the problem appears. Test the steps once yourself before sending the report.