What makes a good bug report?

What is a bug report in software development?

One of the most important aspects of a tester’s job is not just finding issues, but providing comprehensive and concise bug reports detailing these. Without this report, the problem may not be understood, or the development team may not be able to replicate it. This could result in the issue not getting resolved – a situation no one wants!

How do you write a good bug report?

Improving and honing your descriptive skills should be an on-going process if you’re a tester – but you should always look to include the following five key components in your bug reports if you really want to provide the development team with everything they need to find, debug and ultimately solve any issue efficiently.

1. Give it a good title

Seems obvious! But giving your bug report a good title is important to ensure it can be identified and tracked with ease. At Box UK, we use JIRA to track all our tasks, user stories and bug reports, so some projects can end up with a large number of tickets associated. Good titles are necessary here to trace issues so that things don’t get lost!

A good title should be clear, relevant and descriptive – so that a general idea of the problem can be grasped immediately. I usually follow the format “what is the problem, and where?”. If it is useful to also mention the action you carried out that produced the issue, include it – but be wary of keeping your title succinct!

Example of a bad title:

• Site not working

While concise, the above title simply does not provide enough information. In what way is the site not working? Is it broken only for certain users? Is the issue with the front-end or back-end? Is it only not working in one browser, or device?

A better title might be:

• Login into admin as SuperUser01 throwing 404 error – Chrome only

2. Create a informative description

Before you go into the detail of steps to replicate the issue, you need a brief description of the issue to provide valuable context and so help the developer quickly understand the problem. I always assume that whomever is reading my report has never seen this part of the feature or work before, so will need to be easily guided by my description.

Also think about who else might read your bug report. It’s not just developers, but project managers and your fellow testers – who, again, might not have seen the work before. As with your title, your description should cover the main points that clarify the issue – including what environment, what browser etc. – but should not be an essay!

Example of a bad description:

• Seeing an error on the screen.

Example of a better description:

• When accessing the content explorer in the admin as TestSuperuser on the QA environment, selecting the create new documents icon is throwing an error message – “Cannot read content”. The other actions in the admin seem unaffected.

3. List the steps to recreate

Provide clear, concise steps to replicate the issue, that should let anyone clearly see what you did to see the problem, and also allow them to recreate it easily themselves. This section should also include results – both expected and the actual – along with relevant URLs.

This perhaps might sound like overkill, but sometimes we can miss out assumptions (for example, being logged in as a certain user) that the reader is oblivious to for whatever reason, which could be key to the issue! And while some of this information might seem obvious, and could even seem self-explanatory to the developers, again remember that someone else outside the team might have to either pick up the ticket or test the work later on, and so will need to quickly understand where they need to look and what they need to do.

Example of bad steps:

• Open content explorer
• Expected: Create documents. I can’t create documents.

Example of good steps:

• Log in as TestSuperuser on www.qa.examplewebsite.net/admin
• Once page has loaded, select content explorer
• Select upload image
• Select cancel
• Select create documents
• Expected result: The create document window appears and the user is able to access the relevant fields.
• Actual result: On selecting create documents, no create document window appears and an error message is thrown. The error message states: “Cannot load content” – see screenshot. This is only affecting the TestSuperuser, and only when you attempt to upload an image before you try to create a document. The rest of the functionality in the admin is working as expecting.

4. Provide supporting information

Be sure to include any supporting information you might have that could aid the developers. Screenshots for example (as noted in the steps section above) are an excellent way of showing what you have seen. But again, these need to be relevant and also annotated if necessary to provide further context – otherwise could simply be arbitrary. Consider including the URL address bar in your screenshots, and if you have checked the console for errors, include that too – this could be invaluable to confirm where within the site or software it happened. Additionally, sometimes things can’t be captured in a screenshot and a video is more useful. This can be really handy for JavaScript front-end issues, for example, where specific actions are required to recreate that can’t be shown in a still image.

Whether it is screenshots, videos, URLs or written information however, make sure you’re including all information that’s of worth. Don’t forget to mention the environment you are testing on, for example, as the project could have multiple environments and an issue may only be occurring on one of them. If error messages are displaying, include the error message details.If functionality is not working for certain users, detail who these users are and if necessary provide information on how the developers can log in as this user type (although if this means you need to provide password information, remember not to post passwords on reports/tickets that may be accessible by all!).

5. Label with a severity rating

Bug reports can be categorised according to the severity of the problem. It is important for a tester to accurately report what type of risk an issue presents; making sure to have a consideration for the business value. For example, front-end issues – like a button not appearing aligned – is going to be lower priority than, say, a 500 error when a form is submitted. Typically, issues with functionality should be ranked as higher priority than those that are styling specific, and major issues such as entire site fails or core functionality simply not working should be ranked critical.

However, something like button alignment might be ranked more than a ‘low’ priority issue if the button is not aligned in such a way that it affects users carrying out a critical action on the website. For example, if the issue is related to a call to action to complete a transaction this could negatively impact the payments you receive, and lead to you missing out on revenue; subsequently, this would likely be ranked a high severity. It is important to have business awareness though, to be able to make these kind of judgements effectively.

Other considerations

As well as severity, you may want to categorise the type of issue in your bug report. As mentioned above, there are design issues and functionality issues, but there are also many more such as server, regression, performance, validation and configuration issues. This is again something that may be worth noting, as it can help the issue get investigated and resolved.

The report should also be assigned to the correct person. Who this is will depend on the project, but this should have been defined and agreed beforehand as part of your project development process.

Sometimes extra details can prove invaluable – like mentioning whether the issue is intermittent, despite the steps, or linking to previous tickets that may be related to the problem at hand.

Finally, while these guidelines have been aimed at testers, they can also be very useful during the User Acceptance Testing (UAT) process, when clients need to provide feedback to your team. UAT testers should be encouraged to report back their findings in the format detailed above, as this will help facilitate a quick and effective feedback loop and so be beneficial for all involved. Be sure to have these conversations with the client prior to the UAT phase, and work with them to make this process easy for everyone.

Conclusion

A good bug report is all about communicating and describing – and taking a little care and time to do so will pay dividends for all involved. Of course, there are no set rules, and all teams work to different processes, but as long as you consider the key components – title, description, steps to replicate, evidence to support, and severity rating – you can’t go wrong! Remember that being concise and thorough is of paramount importance, as is thinking of your audience.

Done well, these bug reports will help enable a swift, cost-efficient project lifecycle. And your development team will be busting those bugs in no time!