How Do You Write a Good Bug Report?

Andrzej

Imagine for a second that you are a software developer and you are alerted by a bug notification saying ‘The screen is blank!’ or ‘I get an error message on user profile’. You are ready to fix the bug, but instead, you have to hunt it down first.

 

The first ever computer bug

 

Let’s be totally honest, bugs will inevitably occur as everybody interacts with technology differently. Finding and fixing them can take time, and from a users perspective the sooner they are resolved the better. One way to help speed up this process is by helping your developer get to the route of the problem as quickly as possible.

When you send information to your developer about a problem, this is called a “bug report”. In your bug report, it is important to be as clear as possible about the issue you have found so that they can work out what has gone wrong. Here is a list of our recommendations on how to report bugs efficiently and ensure that they can be easily found and quickly fixed by developers.

  • One bug per bug report
    • Even if you have multiple issues, it’s important to file separate bug reports. This will help to avoid duplication or missing issues.
  • Give it a meaningful title
    • This should be a concise summary of what is wrong. For bonus points, you can add a section of where the issue is happening, in square brackets at the beginning of the issue.
  • How did you find the issue?
    • It’s important to note down all steps that you have made before the issue happened. This will help developers reproduce the bug, which then the Quality Assurance team would verify when it has been fixed. It’s a good rule to recreate the bug before filing an error, issues should be replicable.
  • What do you see?
    • Describe the problem you encountered. If you’re testing a web project, attach a URL to the page where you encountered the error.
  • What should have happened?
    • Let developers know what you expect should happen. If the text is incorrect on the label, write down what it should say. If one of your buttons has incorrect colour, mention what colour should be used.
  • An image is worth a thousand words
    • Where did it happen? Take a quick screenshot and, if possible, annotate it and attach it to your report. Even better, sometimes it is easier to record a short video to show the behaviour of your application or website.
  • What’s the environment?
    • It’s essential to report the environment you were testing on. This means not only which version of the software but also the device and/or browser. Tell your developer whether it is a development, staging or production version, and report your device type, OS (Operating System) version, web browser and build version (on mobile devices you can find this info in your settings>about phone). Some issues may only be seen if your browser is zoomed in, so please include all those details in your report.

Now let’s look again at one example mentioned at the very start, and how your bug report can be improved.

How not to report a bug:
“I get an error message on user profile.”

A good bug report:
Title: [Profile] Error 500 on updating username
Steps to reproduce:
Login to the application
Go to Your Profile tab using bottom navigation
Tap on Edit Profile
Select your username, edit and press update
Dialogue with error “500 Internal error” appears
Description: On editing the username in the profile, I get an Internal error. The username stays unchanged.
Expected result: I can update my username without any errors, a success message “User updated successfully” appears.
Affects version: 0.9.1 Android
Environment: Samsung Galaxy S9, Android 9.0

What happens next?

Bug reports are placed into a backlog. It will be assessed and given a priority level and one of the team will be assigned to fix it and schedule for future release. Some of them might be rejected, others may be marked as duplicates. After a developer corrects the bug, the QA team has to verify that the issue has been resolved and approve it for release.

The more information you supply, the quicker the issue can be reproduced and fixed. We hope that those few points will make it easier for you to tell your developers about any bugs you find more efficiently. Remember, good bug reports help developers to improve your product and make it more reliable, so it’s a win win for everyone.