How can we make our bug reports more understandable

Reporting bugs is an unavoidable part of SDLC and it is an integral part of any tester's job. It's usually done using bug-tracking software such as Jira, Rally, Bugzilla, Mantis, Azure DevOps, etc. In this post, I will share a few general (common-sense) tips on writing a clear and useful bug report. Well-written and understandable bug reports save time and can be a significant contribution to the quality of the product - especially if we prioritize those bugs which negatively impact the user experience and block the core functionalities of the application under test. So let's see what we can do to make our bug reports better. 

Root Cause Analysis 

Before reporting we need to make sure our defect is valid, we should check for human errors such as an outdated (no longer support) app version, configuration settings, user or systems settings - checking the logs can help us a lot here. Root cause analysis can be added in the form of testing notes to the defect ticket. If the tester is technical and has access to the source code (for example, a git repo on GitHub or similar) they can pinpoint the direction of where the defect is located, by following the code - might be needed to run the code locally with a debugger. Don't let this part intimidate you, in many places, this is not required from a tester, and it's not as daunting as it sounds when it is.

Defect Title 

The title should summarize in short what the defect is about, just by reading the title others should have a clear picture of what our defect is about. Avoid vague titles such as “Checkout Error” - be descriptive, precise, and concise by summarizing your defects, for instance: “Unexpected Exception Thrown Upon Clicking the Checkout Button in Firefox“. Most serious companies will have pre-defined naming conventions that you should use when reporting bugs, which will make your life easier - just remember to be precise and succinct - a good title will immediately make it clear as to what the bug is about.

Steps to Reproduce 

We need to make sure that our defect is reproducible, we need to add exact steps on how to reproduce the issue, the single-step should represent a sing action, avoid “and“ and “or“ in the repro steps as these add unnecessary ambiguity. To goal is that anyone can reproduce the same result by following the steps, even someone who is new to the project and not familiar with the product. We can also make use of our test cases and test scenarios if the defect was discovered while executing those and have instant steps to reproduce our defect - many test management products allow us to do this by creating a defect from the test execution and linking them together. This is especially important when dealing with bugs reported by customers - they will often report unclear issues and you will have to figure it out, after investigating, and add proper details on how to reproduce the issue.

Include Screenshot(s) 

A picture can tell a thousand words and having screenshots of discovered defects can help save time needed to investigate the defect and speed up the overall defect resolution. Generally, for web applications, a screenshot of the full screen is preferred, so we can see the URL in the browser if relevant having the console (from the developer tools) visible in the screenshot can help if it shows an error(s) relating to the issue we have found, requests and responses from the network tab can also be very insightful. In some cases including the time when the screenshot was taken can be useful. Leveraging screenshot tools can be helpful as well, such as highlighting the parts of the screenshot most relevant to the bug report - an error message, part of the form which is missing validation, etc. A defect report should not contain only the screenshot, images are there to supplement the defect report and provide additional context.

Screen Recording 

Not required for all defect reports, but it can be helpful in some cases, especially for an intermittent issue that is not always reproducible and are hard to describe. Another good use case for a screen recording would be to provide aid in reproducing an issue with a lot of very particular steps needed to reproduce it - a full customer journey leading to the problematic outcome.

Actual and Expected Results 

Once we make sure that our defect is valid (a deviation from the expected behavior established in the user stories or system specifications) we need to include Actual results and Expected results. Expected - what the system should be doing and Actual - what has actually happened. Short, concise, sentences should be enough for these results.

Logs and Stack Traces 

If available, we can include details from the log and stack traces of the failure to help speed up the investigation of the defect, so the developer who is assigned to fix that bug knows where to start with the investigation right away. Stack traces can see very long and confusing, but even if you are a junior tester you should be able to find them and include them in the bug report - you don't have to be able to read and comprehend the entire stack trace right away, just being able to find and identify it is a big help. Searching the logs can help you track down a stack trace, just get familiarized with the tool used for logging in to your company so you don't spend too much time using it.

Software Version 

Whenever it is applicable, we should include the version of the application in our bug ticket as it helps narrow down the issue. For web applications, it is useful to include the version and the name of the browser which was the user, and sometimes the operating system as well - similar goes for mobile and desktop apps as well. Particularly important for regression bugs to have the affected version included.

Database Query Results

When we have a query that returns data helpful in understanding the defect we should include the results of such a query in our bug report. Info gained from a SQL query, or non-SQL query, can be especially helpful when dealing with data-related defects.

Determine Severity and Priority

Severity is used to tell us how significant is the impact of the bug on the system - if login is not working that is considered a very severe issue as it's blocking a lot, if not most, of core functionalities. Priority, on the other hand, provides an estimate on how impacting the issue is for the end-user - for example, there is some incorrect info on the website, it's easy to correct, so the severity is very low, but, it could have negative legal implications for the company. If you got a well established processes in your workplace, you might have decision charts to determine priority and severity depending on the type of the issue, the impact it has, etc.

Something like this

Keep it Professional

Last but not least, when reporting defects it is important to stick to the facts and to use language which is professional and respectful, avoid adding personal opinions, suggestions on how the issue can be fixed, passing blame and accusing, statements on how the issue could have been prevented, etc. Leave the emotional stuff for the retrospective. 😄

O hope this article was helpful - thanks for reading!