How to Write an Impactful Bug Report that Engineers Will Love

Having played the role of Test Lead on many projects throughout my career, I have seen countless bug reports. From this experience, I can tell you that a bad bug report not only provides little value, but costs precious time, something most projects usually cannot afford — especially as more organizations embrace continuous integration and continuous deployment (CI/CD) pipelines. There is nothing more frustrating to a project team during triage than having to send a bug back to the tester due to confusing or incomplete information.

Writing an impactful bug report will impress upon the reader its importance, helping the project team to easily understand and prioritize the bug’s impact. Being able to quickly prioritize a bug helps the project team decide how, where and when to allocate resources for a fix.

An issue is deemed the highest priority when it impacts the most users or features critical to the overall application, garnering immediate attention. Priority is also determined by how much a potential bug impacts the customer’s experience and/or the company’s bottom line. So even if it seems minor on the surface, it could have a much bigger impact to the customer.

The job of a tester is to find the bugs, report them in a clear and concise manner, assess the severity of the issue based on knowledge of the application-in-test, provide detailed reproduction steps and include supporting evidence. It all begins with the bug title.

A Clear and Concise Title

An impactful bug report immediately tells anyone reading it what the problem is in the title.

“Got an error” is probably the most useless title I have ever witnessed. It tells us and the customer nothing. As Test Lead, I would immediately kick this report back to the tester and have them fix it.

An impactful bug report immediately tells anyone reading it what the problem is in the title.

An example of a decent title is something like:

“Java Runtime error when selecting Checkout in Shopping Cart”

This title at least provides an idea what the problem is. I could prioritize its impact, provided the bug detail contains enough information. However, if I’m testing multiple environment types, this title alone does not tell me if the issue exists in all environments or a single environment. I would also send this back for more information.

An impactful title should contain as much information about the issue as possible. Information such as test environment, test area, test case name, test step and the issue:

“Web – Checkout – TC 1802 – BUY EGC – Step 4 – Java Runtime error when selecting Checkout in Shopping Cart”

I can now glance at the title and I immediately understand what and where the problem is, and I have a good idea how important it is.

Of course, depending on what software you are using to track bugs, you may be limited by the amount of characters you can enter or that can be seen in a quick view of the bug list. If this is the case, do your best to offer as much concise information in the title as possible.

Now that we’ve got a clear and concise title, let’s move on to the body of our bug report.

A Detailed Problem Definition

The body of the bug report gives as much detail about the issue as possible. As with the title, “Got an error” is not useful information. Having already put as much concise information as we could fit in the title, the description should contain a more detailed review of the problem. This could include:

• A summary of the issue in technical detail or in layman’s terms. This is useful when your audience contains non-technical business stakeholders
• Test Case Name/ID where the issue was found. This is helpful if the test case is out-of-date and needs to be updated to reflect the current feature state
• Exact Test Steps to reproduce the issue
• Expected Results (what should have happened)
• Actual Results (what really happened)

Supporting Evidence

We have now gone into more detail about the issue and provided the steps to reproduce it — what else can we provide in the bug report? Evidence. Adding the following evidence, if available, will help the project team quickly set priority and help the developer track down the root cause efficiently:

• Error text (and error ID if present) if an error is thrown
• Test environment where the issue was found (make sure to note if the issue is reproducible on all environments-in-test, some but not all, or just one)
• Screen captures and/or video showing the steps leading up to the bug
• Logs (Device, Crash, Network, etc.) that are captured at the time of the issue and can help the developers narrow down the problem faster
• Number of times the issue was reproduced (sometimes an issue is legitimate, but intermittent)
• Any other supporting evidence that can be included

Congratulations! You have now written an impactful bug report that the project team and developers can use to understand, prioritize, identify the problem and most importantly, fix.

If you have more specific questions about writing impactful bug reports, reach out to our team. Here at Applause, our team leads edit and triage thousands of bug reports every week, and we specialize in putting together bug reports that development teams can easily understand and act on.