The Essentials of Writing a Good Bug Report

As a developer, I can see first hand the difference that a good bug report makes. A poorly written issue gets resolved much more slowly because of two factors:

• I spend more time trying to understand it, and
• I often leave them waiting until there are no better written issues left.

In this article, I’ll show you how to write a good, easy to understand bug report.

Target audience

Firstly, think about your target audience. It will be very likely pretty broad:

• developers—as the ones who need to understand the issue and provide the fix
• testers—so they can confirm the issue is gone after adding the fix
• managers—to assess the importance of the issue

It would be perfect to have a description clear enough that even the newest team member can make sense of it. This means that it’s better to err on the side of being too verbose and include some ‘common knowledge’ about your product in the ticket.

Troubleshooting

Some great help that a person who writes a ticket can provide for developers is a little bit of troubleshooting. You don’t have to find a root cause of the issue, but some effort can go a long way: both in helping your colleagues and helping your progress in your career.

Errors in console

I’ve seen managers who were truly impressed by the fact that service desk colleagues opened dev tools to see whether there were any errors in the console when the application failed. As a developer, those logs are often enough for me to pinpoint the issue in the code. In some cases, by just having the errors included in the ticket, as a text or a screenshot, I can immediately jump into resolving the issue. The logs are particularly helpful if I cannot reproduce the issue—in those cases, they can be the only information I have to find the error.

Backend requests

In my experience, many backend bugs are reported first on the frontend—because this is what users use and where they see things going off the rails. Something as simple as checking out the network tab can be enough to correctly assess where the issue originated—you can see the errors returned by the server, see what parameters were sent, etc. Even if this doesn’t clarify things for you, you can include request and response pairs in your ticket, and most likely, developers will get a lot of information from it.

Content checklist

Let’s take a look at what to include in your bug report.

Title that summarizes the issue

A clear title helps a lot. It should make it clear what is broken and where it’s broken at first glance. Clarity is important because not every developer will have enough business context to know what behavior is correct. So, for example, instead of “Bug: Cashback on discounted products”, you can write:

• “Bug: Cashback missing from the discounted products”, or
• “Bug: Cashback should not be applied on discounted products”.

The ‘where’ is important as well. If your team has many developers, then they will immediately know who worked on a given part of the application recently, and they will be able to auto-organize efficiently.

Exact steps to reproduce

A list of steps needed to see the issue happen in the application. Besides the most simple bugs, this is the key to resolving the issue and confirming that it’s really gone. Good reproduction steps contain all the relevant information, such that anybody from your audience could follow them and see the bug in action. This often includes:

• the environment—the best is to have an example at the testing or staging environment, so the issue can be repeatedly observed without affecting customers’ data,
• exact URL,
• any clicks, typings, or other operations that are done in the app,
• files and all the other inputs that were sent to the application,
• any other thing that could be relevant to getting the issue.

Note that if you cannot reproduce the issue, then most likely, the developer will not be able to either. This doesn’t mean it shouldn’t be written and cannot be addressed—it just means that troubleshooting will be more time-consuming, and fixes will be done based on educated guesses, and they will be difficult to check for correctness.

Expected behavior

As with the title: what should happen instead is not always clear for people who work far from the business. Making the expectation explicit, from the very beginning, can save time in communication or proving a wrong fix.

Screenshot

Screenshots provide a lot of information and can be digested at once. Besides that, taking them and including them in the bug report takes only a few moments. There is no reason not to include them in the bug report—even a white screen of a failed app can contain interesting information in the address bar.

Versioning

If your team has some version identifier, it makes sense to include it in the bug report. Often, I’m able to save a lot of time by comparing the affected version with the repository history. For example, maybe the ticker was written with an older version, and the bug has been fixed since then. Or perhaps the retesting happened before the fix was delivered to the environment. In any case, chasing a bug that is not there is neither productive nor fun.

What next

If you are interested in learning more about testing or programming in general, you can sign up here to get an occasional email from me.