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 be feel exciting, especially if it's an interesting scenario. But the way we report it can be as important as the impact it has on the system.

A badly 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.

I’m gonna get into the most important details that a bug report should include, and also provide some bug report examples to help you improve the way you write them. You’ll also get a downloadable bug tracking template to get you started!

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. Many bug tracking software already provide 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 what the problem is. It should be concise enough to be easy to read, but descriptive enough so other people can understand where the problem lies. A good title can be something like “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 ends up trying to reproduce the issue or verify the fix will be able to 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 that it’s not expected. However, I would not say the expected result is “exception is not thrown”, but rather say what action the button should perform, i.e. “the setting dialog opens”.
• Actual results: This is pretty much 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, there are other pieces of relevant information that 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 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 that you also include them, whether in the steps to reproduce (for example, “log in with user andreea@theqalead.com”), 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, be sure to mention that.  

Tips To Creating A Good Bug Report

• Limit yourself to a single bug per report. If you discovered more bugs in the same areas, you can probably link them in 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 already 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 should be easy to read, and the steps should be easy to follow.
• Don’t make assumptions about why the bug happens (unless you are actually 100% certain you know what caused it).

Bug Report Template

Now I’d like to share with you some templates for a bug report. You can copy them or modify them based on your project’s needs.

Jira Bug Tracking Template

Jira is a very common issue tracking tool from Atlassian. If your team is using it, the bug issue type is probably already configured. You, as a tester or a manager of the software development team, can set up a workflow for the bugs’ life cycle. 

You can also add custom fields, for example for the environment or a special 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 important 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 spending time to set 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 really fit in the other columns

Conclusions

Writing a good software bug report is an essential skill for software testers, so pay extra attention to follow 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, stay in touch with more news and trends in the software testing process by subscribing to The QA Lead newsletter!

Also Worth Checking Out: MODERN QUALITY ENGINEERING: HOW TO REDEFINE QUALITY STRATEGY FOR AGILE FRAMEWORKS