How to Write a Bug Report (+ Free Template Download)
Knowing how to create an effective bug report is a big part of a software tester’s job to maintain quality assurance, so we spend a lot of time logging bugs in our bug tracking tools. Finding a bug can feel exciting, especially if it's an interesting scenario. But how we report it can be as important as its impact on the system.
A poorly written bug report can cause a lot of friction between team members, namely between the testers and the developers, which can create blockers for the bug fixes and ultimately ruin the user experience.
In this article, I'll share essential details, like how to:
- Master Bug Reports: Learn the key elements every effective bug report should include to streamline communication and expedite fixes.
- Boost Team Harmony: Discover how well-written bug reports prevent friction between testers and developers, leading to smoother workflows.
- Free Downloadable Template: Get a free, downloadable bug tracking template to jumpstart your efficient bug reporting process.
Key Bug Report Elements
No matter the type of application you are testing, whether it’s a desktop, web, mobile app, or an API project, there are some key elements every good bug report should include. Most bug tracking software provides fields for these elements, including:
- ID: If you’re using a project management tool, such as Jira, an ID will automatically be assigned to any new issues that are opened. There are also test management for Jira tools for bug tracking
- Title/Description: This is a short description of the problem. It should be concise enough to be easy to read but descriptive enough so others can understand where the problem lies. For example, “sorting items by price doesn’t work when a filter is applied.”
- Steps to reproduce: Include here as many relevant details as possible. Make sure that whoever tries to reproduce the issue or verify the fix can do it just by following the steps. Don’t skip steps because you assume that everyone will implicitly know that they should perform some actions even if they are not mentioned; include them in the bug report.
- Expected results: Again, don’t assume people already know how the application is supposed to work. Of course, if you get an exception in the UI when you press a button, you know it’s not expected. However, I would not say the expected result is “exception is not thrown” but rather what action the button should perform, i.e., “the setting dialog opens.”
- Actual results: This is self-explanatory—you should describe what happens in the application once all the reproduction steps are performed.
- Severity: This represents the impact the bug has on the AUT.
- Priority: How fast the bug should be fixed. A higher priority means the bug should be placed higher in the backlog and fixed sooner.
Other Important Information To Include
Apart from the elements mentioned above, other information may be relevant, especially when entering data into a bug reporting tool. They can depend on the project type, the project requirements, or even the bug itself:
- Software version: The build number where the bug was identified. This can help isolate the builds where the issue was potentially introduced and identify the code that caused it.
- Attachments: These may not always be needed or available, but they usually bring a lot of value. Consider providing screenshots or recordings of the issue found, log files, stack traces, network requests and responses, etc.
- Test data: Sometimes, the bugs we find only reproduce for specific sets of data. If that’s the case, make sure you include them, whether in the steps to reproduce (for example, “log in with user [email protected]”) or in a specific field in the bug tracker tool.
- Environment details: If the bug only reproduces on a specific operating system, browser, or development environment, mention that.
Tips For Creating a Good Bug Report
- Limit yourself to a single bug per report. If you discover more bugs in the same areas, you can link them to your issue tracker. Including more than one defect can cause confusion and delays in the potential bug fixes.
- Check-in your tracking system to make sure the bug wasn’t already reported. If it’s already opened, add any relevant details you found that weren’t submitted to the original bug report.
- Try to reproduce the bug more than once. You can try to find the shortest way to reproduce it (using the least number of steps).
- Don’t get lost in irrelevant details. The bug report and steps should be easy to read and follow.
- Don’t make assumptions about why the bug happens (unless you are 100% certain you know what caused it).
Bug Report Template
Now, I’d like to share with you some templates for bug reports. You can copy or modify them according to your project’s needs.
Jira Bug Tracking Template
Jira is a very common issue tracking tool from Atlassian. If your team uses it, the bug issue type is probably already configured. As a tester or a software development team manager, you can set up a bug tracking workflow for the bugs’ life cycle.
You can also add custom fields in Jira, for example, for the environment or a unique field where the functionality tested is added. Or you can add a default description with all the information you want to be included in each bug report. Here’s one I created:
Now, when I want to create a new bug, I will have this information pre-filled. Here’s my bug template in Jira, using custom fields and a default description:
It has the vital information we said the bug needs to include:
- A title (“Sample bug”)
- Inside the description: the preconditions, the repro steps, and the expected vs actual results
- A custom field for the environment
- A severity and a priority, selected from drop-downs with predefined values
- I left the assignee empty. Depending on your project conventions, new bugs can be automatically assigned to a specific team member, or whoever starts working on it can assign it to themselves
- A label—this can be helpful if you want to track which functionality is impacted, for example
- A due date—may not be completed until the backlog has been prioritized
- The reporter (which in this case is auto-filled with the Jira user who created the bug)
Optionally, Jira has several integrations, and the bug can be linked to test cases, Git branches, or even pull requests.
You can also use their bug tracking template as a project template if you only need Jira for defect tracking and don’t work in an agile environment.
Excel Bug Tracking Template
Some teams may use sheets for their bug tracking system. I find them useful for very small projects where setting up an issue tracking tool is simply not worth it or for reporting bugs on new features that are still under development.
You can use Google Sheets/Docs, or Microsoft Excel/Word – either way, a bug template can look like this:
The columns reflect the information the report should contain:
- The ID (Excel will know how to automatically increase the value each time a new row is added)
- A title
- The steps to reproduce
- Expected and actual results
- The reporter name
- The severity and bug priority—here, I used drop-downs because the values should be pre-set
- Environment
- Additional information: This is for anything else worth noting that doesn’t fit in the other columns
Final Thoughts
Writing a good software bug report is an essential skill for software testers, so pay extra attention to the best practices explained above. You can also rely on the examples of bug tracker templates I provided. They can be adjusted to different tools you are using, such as Trello or Asana.
If you liked this content, subscribe to The QA Lead newsletter to stay in touch with more news and trends in the software testing process!
