How to write a bug report effectively: examples and templates
Learn how to write an effective bug report that will make your engineers love you.
Bug reports are a necessary part of any software development process. The report is the primary communication between an engineer and their stakeholders about what's broken, why it's broken, and how to fix it. However, most people don't know how to write a bug report effectively. This article will help you learn the art of writing a good bug report by giving you examples and templates for your reference. We've also included copy-paste and downloadable bug reporting templates in this article that you can use or edit as needed.
Bug report format
Information to include in the bug ticket
Best practices for filing bug tickets
The most important thing to understand when reporting a bug is that the reader should be able to reproduce it on their computer with only the information you provided. If you are unable to reproduce the bug before filing the bug ticket, try providing as much details about what led up to and happened during this issue (i.e. what actions you were performing, time when it happened, etc.)
Title
Briefly describe the bug, i.e. "Calculator: incorrect result of multiplication". Try to be concise, but specific here. For example, "Broken landing page" doesn't help the reader understand whether the issue has already been reported and what exactly is wrong: Is it not accessible? Is the layout broken? Is it just a typo in one of the headlines?
Steps to reproduce the bug
Describe what actions you took before you encountered a bug. It can look something like this:
- Go to ExampleURL.com
- Click button A
- Select option B
- Type "123"
- Click Enter
It is best to try and reproduce the bug yourself before filing a bug ticket. That way you can be sure that the steps provided will lead to a bug you are reporting.
Resulting and expected behaviour
Specify what happened compared to what you expected to happen. Examples:
- Result of operation "2x2" should be 4. In reality it is 5.
- I get an error "404. Page not found." on ExampleURL.com/blog/bug-report-template. The page with this URL exists and should be accessible.
Screen recording or screenshot
Screen recording/screenshot/technical data: Mac/Windows/Linux/ Chrome OS
The fastest way to make a screen recording or screenshot for a bug report is to use a dedicated tool like Bird Eats Bug. Together with the video and screenshot, it automatically captures technical information that will help engineers fix the problem a lot quicker. This way you also don't need to worry about providing system information and typing up steps to reproduce the bug - they will be documented automatically as well.
Screen recording: Mac/Windows
There are many screen recording tools for you to choose from. Mac users can use QuickTime (see tutorial here) or by pressing Shift-Command-5. On Windows 10 you can use the Xbox app (see tutorial here).
Screenshots: Mac/Windows
In certain cases (i.e. typo on a landing page) there's no need to record a video - a screenshot is sufficient. There are tools built into your operating system. See how to make a screenshot on a Mac here, Windows - here.
Technical data
In some cases, you need to provide console logs and network data to help developers investigate bugs faster. There are two ways to capture such technical data on Mac/Windows:
- Doing right-click on any page element and select Inspect to open Developer Tools.
- Or using a keyboard shortcut to open Developer Tools: Ctrl + Shift + J (Windows), Cmd + Opt +J (Mac)
System information
Operating system (including version): Click here to find out this information.
Browser (including version): Click here to find out this information.
Engine
Screen and window size
Device: Desktop / Tablet / Mobile
Time (including time zone): At least approximate time when you encountered a bug.
Test Data [If relevant]
Sometimes, bugs are only reproducible with some specific test data such as an existing user account, an uploaded image, an import file, browser extension or the combination of specific conditions. In order to reproduce the bug, we need to provide such data so that engineers can use it to replicate the issue or locate the data in the system to understand the problem.
Impact [If known]
In case you know how many people are affected by the bug or how much revenue is being lost because of the bug, provide this information. It will help engineers and product managers assign the correct priority.
Bug reporting: the easy way
If you want to simplify filing bug tickets and provide more information to the engineers at the same time, you can quickly add Bird Eats Bug to your browser (Install the Bird Eats Bug Chrome extension and open right away when recording a bug).
That way you will not need to provide any steps to reproduce the bug, system information, console logs, network information, or upload a separate file with a video or a screenshot.
Record the bug and share with your team
You can make a recording right from your browser (no need to install or open a separate application) and then simply send a link to the engineers or product managers. Alternatively, you can include the link to the recording in the bug ticket.
Help engineers understand and fix the bug faster
Because all the technical data will be recorded automatically, you will also avoid situations when more information is requested by the reader. Below you can see the types of information collected without any work from your side.
You can learn more about how to report bugs with Bird Eats Bug here.
Bug report template: Jira
Jira is very popular for bug tracking, so it's very likely that your team would be using it. To create a bug ticket, you can copy and paste the information below into a Jira issue. It's better not to fill out priority, assignee or other fields in the ticket - these would be handled by product managers and engineers. Just send a link to the Jira issue and they will take care of the rest.
Bug report template: GitHub
If your team is using GitHub for tracking development issues and bug reporting, you can copy the text below and paste it into a GitHub issue. It will automatically be formatted as you can see in the picture above.
Bug report template: GitLab
For Bug reporting with GitLab, you need to copy the text below and paste it into a new GitLab bug ticket. Once you hit save save, the correct formatting will automatically be applied.
Bug report template: Trello
You've been using Trello to handle bugs? Copy the text below and paste it into a card. It will automatically be formatted as you can see in this picture above, or create your own template from this card for future use.
Bug report template: Asana
In case your company is using Asana, copy the text below and paste it into a new ticket. The formatting will be exactly the same as shown in the picture above.
Bug report template: E-mail
If you are not sure what bug tracking software your development team is using, you can send your report via E-mail. It is best to send it to a Product Manager. They would be able to quickly evaluate if it's a known bug, help you find a workaround and prioritise the bug ticket.
You can copy and paste one of the templates below into Gmail, Outlook or any other E-mail client you use.
If you are using Gmail, you can also save this template for future use. This way you will always have the information pre-filled. For that you just need to save it as a canned response. See how to do it here.
Bug report template in Excel and Google Drive (Sheets & Docs)
Google Drive templates can be a good way to report a bug to your product team. They will provide engineers and PMs with very structured information.
You can choose the format you prefer (either Google Sheets or Google Docs), make a copy of the document and customize it for your own needs.
Go to Free Google Sheet Bug Report Template
Go to Free Google Docs Bug Report Template
Bug report template: Microsoft Office (Excel & Word)
Google Drive templates can be a good way to report a bug to your product team. They will provide engineers and PMs with very structured information.
You can choose the format you prefer (either Google Sheets or Google Docs), make a copy of the document and customize it for your own needs.
Go to Free Excel bug report template
Go to Free Word bug report template
Performing exploratory testing? Click to download our exploratory testing template.
Final thoughts
All in all, it is important to provide as much detail about the bug you experience so that engineers can quickly reproduce and resolve the issue. It also helps engineers get a better estimate of how long the resolution might take. And the more information developers have, the faster they are able to implement a fix.
It's not uncommon for product teams to receive like the ones below:
- Nothing works
- Page doesn't load
- Everything crashes
- I don't see anything
- X is broken
- etc.
Avoid writing non-descriptive information like the points above at all costs. It will help both you and people, fixing the bug, to save time and frustration.
Last but not least, If you found this guide helpful, do share it with your peers who might want to significantly reduce manual work and avoid follow-up questions from engineers.
Data-rich bug reports loved by everyone
Get visual proof, steps to reproduce and technical logs with one click
Continue reading
.png)
Put your knowledge to practice
Try Bird on your next bug - you’ll love it
“Game changer”
Julie, Head of QA
Overall rating: 4.7/5
Try Bird later, from your desktop