The Anatomy Of a Good Bug Report

For almost a century and a half, engineers have called small flaws in machines “bugs”. Nowadays, “bugs” is used for both hardware and software issues in computers and gadgets. Computer bugs have been around for quite a lot of time and with them also came the bug reports.

The first ever computer bug report was documented on September 9th, 1947, by Grace Murray Hopper. She reported that an actual moth was stuck between the relay contacts in the Harvard Mark II computer. The bug was taped to the computer log book.

More on the first bug report can be found here.

Since then, bug reports have been an important part of the whole QA process. They remain as the main tool for reporting faults in programming codes.

This article covers what needs to be included in a good bug report. There will also be a couple of examples for good and bad bug reports, including a short analysis of each one.

What Is a Bug Report?

In website development, a bug report is the main tool used to indicate that a certain piece of code isn’t performing as expected. There are loads of different examples of “bugs” out there, but to name a few:

• A website crashing due to using too much system resources
• Images appear strange on certain browsers or devices
• A webstore is showing incorrect prices for some of the products
• A feature is not performing according to the client requirements

The main purpose of a bug report is to allow the development team to reproduce the issue which has been reported by the QA team. It’s important to have all the required information to make the process of debugging and fixing easy.

Bug reports are used not only to report issues, but also to suggest new features and improvements. As such, most of the guidelines on what a good bug report should include would also apply for suggestions.

Related Article: How to Develop a Quality Assurance Plan for Your WordPress Website

What Should a Bug Report Include?

A good bug report must include precise information about the issue that has occurred. In order for that to happen, the following items, like in the template used by us here at DevriX, need to be present. At Devrix, the template for bug reports is based on these items. It has been proven that they provide enough information about the encountered issues.

• Title – This should serve as a short summary of what the problem is. It’s important that the title is specific about the nature of the issue. It’s the first thing that a developer sees.
• Status – This is an indicator of what status the bug report is at. There can be different types of statues., depending on the management software used (like Jira, Asana, Trello, Mantis, etc.). Some examples:
  • To Be Assigned – When it’s yet to be determined who will be investigating the issues in the report.
  • In Progress – When a developer is working on resolving the reported bug. This status is also used when an update is currently under test.
  • Complete – A sign that the reported bug has been resolved.
• Priority – This indicates the urgency of a reported bug, compared to other tasks and issues. The priority of a bug is tied with the Severity of a bug as it measures the impact on the tested system. The most common priorities are:
  • Critical – Used for issues where all other activities must stop and all effort is concentrated into resolving the situation. This is due to the fact that such issues have a major impact on the project they are reported for and could result in losses for the business.
  • High – Used for issues which should be resolved sooner, rather than later. They don’t have such a major impact, but if there aren’t any critical issues, they should be resolved asap.
  • Medium – Used for issues which don’t have a major impact on the core functionality. It would be good to have them resolved. Such issues need to be fixed after the ones with higher priority.
  • Low – Used for when the reported bug is minor and doesn’t have an effect on the core functionality. It could be a grammatical mistake in a blog post, or the wrong color for a button.
• Severity – Used to show the level of impact the reported bug has on the tested system. The most common classification for a bug’s severity is:
  • Critical – A core functionality isn’t working or the whole software is failing to function.
  • Major – One or more basic functionalities are affected by the bug. Because of that, the tested software doesn’t produce the desired results. Unlike bugs with Critical severity, there will be functionalities which work as intended.
  • Moderate – There is no impact on the core functionalities of the tested software. One or more components are affected, leading to inconsistent behavior.
  • Minor – The impact on the tested software is minor.
  • Trivial – Bugs with this severity don’t affect the functionality of the software. These could be minor visual defects, missing translations, a confirmation message not working, etc.
• Bug Details – The details contain important information about where the reported issue is encountered. The following information should be included (although different organizations may require different (bug) details):
  • The browser where the bug was encountered (it’s best to also include the version)
  • The OS – It could be an issue, observed only in Windows. This also includes mobile OS like Android, iOS and PadOS
  • The branch – This is for unreleased updates ( new features or updates which fix other reported bugs). The branch contains only specific commits, relevant to a feature. This is done so that a change doesn’t interfere with other people’s work on the same project
  • Version – If the tested software is a desktop or mobile application. it’s advisable to include the version where the bug was reported.
• Bug Description – The QA specialist must provide an accurate explanation of the observed problem, along with the steps necessary to reproduce the issue. The specialist should also describe what the expected outcome should actually be. All of these are important to help the development team understand what the issue is, what actions need to be performed to reproduce it and what the correct behavior should be.
• Attachments/Screenshots – An attachment/screenshot allows the specialist to see what and often where the problem is. It can also provide the QA specialist with the steps which were performed to trigger the issue.
• Comments – The comments section isn’t generally used when a new bug report is created, but it’s important to share a few words about what needs to be included in the developer comments (and any following comments) when a bug fix is submitted to the QA team for testing. Developers must include the following items:
  • Link to the commit which contains the update.
  • Explain what the update does.
  • If there are any setup steps that need to be performed, it’s important to explain them.
  • Attach any screenshots/screencasts showing the update in action.
  • Include any notes which the QA specialist needs to take into account when testing the update.

Related resources: Quality assurance work is an essential part of working on every website. That’s why going through the lengthy and detailed phase of testing, fixing bugs and regressions and stabilizing the platform for the launch is related to how much the website will cost.

Writing Tasks for Suggestions and New Features

While running QA tests, experienced testers usually come up with ideas for improvements to the project. Likewise, Project Owners and Project managers need to receive client requests (for features, fixes, improvements) which need to be shared with the development team.

Unlike Bug Reports, the aim of the Suggestions and New Feature tasks is to explain client requests or improvement ideas which have the potential to improve the project (like the implementation of a performance update, adding a feature which would allow for better interaction with the users, etc).

In both cases it’s important to provide a clear description about the feature which needs to be implemented:

• New Features, required by the client – It’s important for the Project Owner/Project Manager to understand what the client needs, review any provided mock-ups and discuss any additional details. Once it’s clear what the client wants, it is easier to explain to the development team what they need to do.
• Suggestions – It’s important to have a clear vision about the project as a whole and how the suggested feature will improve it. That way it will be easier to explain the idea and the benefits it would bring.

Good and Bad Bug Reports: Examples

Disclaimer: The following examples are taken from a QA course project which the author took part in. The goal is to analyze the mistakes that have been made in the reports and how they can be avoided.

Example 1:

Here is an example of a well-written bug report. It includes all the attributes discussed above.

However, there’s one problem with it – its title doesn’t provide an accurate idea about the reported issue. The missing product image could be anywhere on the tested web store.

A better title is “Missing product images in the “People who bought this item also bought” section”. This way the development team would have an idea what the report is about from the title itself.

Example 2:

This is an example of an overall poorly written bug report. The main issues with this example are:

• The title isn’t specific about where exactly the missing price is
• The description does not specify where exactly the issue has been observed.
• The Expected Result doesn’t actually explain what the correct behavior is.

Poorly written bug reports force the development team to spend unnecessary time figuring out what the problem is and where the reported issue is located. The team often must resort to asking the QA Specialist who reported the bug to clarify any missing details…

Example 3:

This is a good example of a properly written bug report. It gives the development team a clear idea where the issue is and how it can be reproduced.

A slight problem with this report is that the reported issue doesn’t actually stop the testing process, meaning that the assigned severity and priority are incorrect. If the QA specialist investigated the issue better, they would have noticed that a workaround exists.

That workaround would have allowed for the Account Registration process to be completed. It’s of great importance to investigate an issue before it’s reported so that no important details are excluded and that the correct severity and priority can be assigned.

In Conclusion

A well-written bug report by the QAs is instrumental in order for the development team to understand what the issue is and how it is supposed to be solved. For this to happen, always remember the following:

• The bug report title needs to summarize the reported issue.
• Provide accurate details – the platform where the issue is observed, the browser (for web applications), the branch where the issue is observed.
• Provide a clear description of what the reported issue is.
• Ensure that the reproduction steps are accurate.
• Write down what the expected behavior should be as opposed to what actually is being observed at the time of the report creation.
• Remember to assign the appropriate task priority and severity.
• Attach all relevant files – screenshots, screencasts, logs, etc.
• Include any additional information that could help the development team resolve the issue.