How do you write a good bug report? And what details should you include? Fear not: in this blog post, we’ll explore the best practices for bug reporting.
So, you’ve just told your developer team that you found a bug. Instantly, you hear the dreaded reply… “I need more information.”
Before you know it, you’ve got an email thread a million miles long.
You can avoid this situation by writing better, more detailed bug reports from the get-go.
Not to worry: we’ll share some tips and tricks on how to write actionable bug reports that will make your developers love you!
How to write a good bug report
Developers are often under a ton of pressure to solve issues quickly without actually having a lot of time on their hands.
They usually face two extremes: too much unhelpful information or too little important information.
For every bug report, we highly recommend using a bug tracker like Trello, Jira, Asana, GitHub or GitLab and implementing a consistent, standardized approach.
Here’s how to write a bug report:
Keep it short and specific.
Make sure it clearly summarizes what the bug is. Having a clear title on your bug report makes it easier for the developer to find later on and merge any duplicates.
❌ Bad: "I can't see the product when I add it, for some reason I try and it doesn't. WHY? Fix it asap."
- includes too many words
- asks for a solution to be implemented
✅ Good: “CART - New items added to cart do not appear”
- it helps the developers instantly locate the issue (CART)
- it focuses on the actual technical problem
When developers review it, they’ll be able to instantly assess the issue and move on to other elements of the bug report.
If your title isn’t enough, you can add a short report summary. And we mean short.
In as few words as possible, include when and how the bug occurred.
Your title and description may also be used in searches, so make sure you include important keywords.
❌ Bad: "The other day I was trying to add stuff to test and nothing showed up when I did that or clicked on the button."
✅ Good: "On [DATE], I tried adding [PRODUCT] to the cart, nothing happened after clicking the 'add' button on the product overview webpage."
❌ Bad: “The design text on the pricing page looks super weird and doesn't seem right. It shouldn't look that big and should be in a different color.
✅ Good: The headline text size and color on the pricing page don't match the original designs.
3. Visual proof/Screenshot
We all know that a picture is worth a thousand words. That stands true for bug reporting.
While it may not tell the whole story, a screenshot or video can add a lot of value by getting your developers to see and understand the problem faster.
Website annotation tools go a long way here to help you drive your point across.
4. Expected vs. actual results
Take some time to explain to your developer what you expected to happen and what actually happened.
Expected result: ”Item should be added to the cart when I click 'add'”
Actual result: ”Item does not appear in the cart”
5. Steps to reproduce
Here is your opportunity to share the steps needed to recreate the bug!
Always assume that your developer has no idea about the bug you found—how does he reproduce it?
As always, keep it simple!
The steps to follow should be comprehensive, easy to understand, and short.
The most important goal of this step is for your developer to experience the bug first-hand.
Use a numbered list here. And if you’ve already managed to recreate the issue several times, you can include the reproducibility rate (example: 12/12 times bug reproduced).
- Search for product XYZ.
- Click on product XYZ in search results.
- Click on “Add to Cart” button.
- Go to cart.
Websites and apps can behave very differently depending on the environment used.
It’s critical that the following information be included in any report your share:
- Operating system (OS) and version
- Screen size
- Zoom level
- Pixel ratio
- Marker.io will automatically collect this technical information
- Use BrowserStack with Marker.io to automatically grab virtual device information and capture cross-browser issues
- Additional info that can be helpful: device type, network connectivity, and battery state
7. Console logs
These logs show developers all errors that occur on a given webpage.
Logs can also include info that them track certain user actions.
In general, including console logs can be valuable for developers as it can help them dig deeper and identify the root of the problem.
It saves them a bunch of time on any issue!
A lot of crashes or errors are hard to replicate, so having the logs can be super informative.
Pro tip: Marker.io adds console logs automatically to every ticket you create.
8. Source URL
One important, but easy-to-forget item is the source URL.
This will help the developers navigate faster, which saves everyone a lot of time.
Pro tip: If you use Marker.io, we’ll automatically include this, too!
9. Severity and priority
By defining the severity or priority of the issue in your bug report, your developer understands how quickly a bug should be fixed.
The severity of your bug can be defined by the level of impact it has on your website or product. Once this has been determined you can label it as:
The priority helps your developer determine which bug they should investigate and fix first. Here you can choose between:
As the bug reporter, you will normally be responsible for identifying the severity and priority.
10. Advanced information
Whether you're looking to write the most informative bug report ever or you're looking to score brownie points with your developer, you can also opt to include the following:
- Reporter name (your own)
- Assigned person (the developer, usually)
- Due date
The bug report checklist: everything you need to consider
After lots of personal experience (trial and error—ouch), research, and talking it over with our developers, we came up with a checklist of ten essential points to consider.
- Visual proof
- Expected vs. actual results
- Steps to reproduce
- Console logs
- Source URL
- Severity and priority
- Advanced info (optional)
Alternatively, use one of our bug report templates that you can copy for your bug tracking process.
Tips and tricks
In general, it's good to keep these basic guidelines in mind:
- One bug = one issue → Don't include multiple bugs in the same issue!
- Avoid duplicates → Always try to search your current issue tracker for existing reports
- Reproduce the bug before creating the bug report → This makes it more likely that the developer will be able to reproduce the problem and identify where it comes from
- Don't forget to KISS: keep it stupid simple → Keep everything as straightforward as possible. Using bullet points or numbered lists can help
- Use a professional bug tracker → This will help you keep everything in one place and avoid losing files and bug reports
- Be kind → Developers are people too and bugs happen—they’re part of the process of making great end products and websites
Using a bug reporting tool to submit bug reports twice as fast
If you’re still using spreadsheets or color-coded Google Docs for bug reporting, you might be wasting a lot of valuable time.
That’s when bug reporting tools come into play.
With a good tool like Marker.io, you can write and submit bug reports ten times as fast, without ever leaving your website.
Reporting bugs and feedback
So how does that work?
We set out to make it as simple as possible:
- See a bug or want to drop feedback? Click “Report a bug”.
- Add annotations, and input details in the feedback form (use our checklist!).
- Click on “Create issue”—done!
2-way integrations and easy bug tracking
Marker.io automatically syncs up with your project management tool.
This means that whenever you click the “Create issue” button, that bug report will automatically be created in Jira/Trello/GitHub… you name it.
In other words: you don’t need to transfer bug reports from your inbox into your PM tool anymore.
And as a QA tester, you can stay on the website for the entire bug hunting session.
Finally, when a task is marked as “Done” in your PM tool, that same task will also be “Resolved” in Marker.io.
And you get a nice little overview of all bug reports in the Marker.io dashboard:
If you need to discuss a specific bug at length, you can do that on our feedback page:
All comments and attachments are, of course, synced back with your PM tool!
Ready to give it a go? Sign up for a free trial here—no credit card required.
Now that you know how to write a bug report and manage your issue tracking system, you’ll save more than just time and money: you’ll save your developer’s sanity.
Now that we've given you the right tools, it's time to use them.
It's just you, and your new weapons: an awesome bug report and a solid bug tracking system.