How to Write a Bug Report: The Ideal Bug Report

Users won't hesitate to uninstall your app if they encounter bugs or glitches. Many beta testers and end users don't know how to write a bug report that includes the details a developer needs to know in order to fix it. If you're a developer trying to sort out the reports you receive, you know there is more to reporting a bug than simply announcing that the app is "broken". Even when testers and users take the time to write a detailed report, it can still be too cluttered or ambiguous to be truly helpful.

The solution to this lies in standardization. Having a standard bug report makes it more actionable for the developer and easier to fill out for the tester or user. We’ve found that having standardized bug reports can save up to 45% of your time.

While different apps and platforms sometimes need additional information, the basics remain the same, so let's take a look at how to write a bug report the ideal way.

‍

‍

Bug reports are the way to let developers know about parts of their code that are not behaving as expected or designed in order to show them what parts of their app need improvement. This can be a daunting task for the developer and is practically impossible without enough information. Luckily, testers can make this process much easier by submitting quality bug reports that have all the clues the developer might need to pinpoint the issue.

A good bug report should contain only one bug and be clear and concise yet informationally dense. It should contain environment details and user steps that allow the developer to reproduce the bug on his side. Without being able to reproduce the bug, developers are essentially stumbling in the dark.

‍

‍

So what should an ideal bug report look like? While there might be small variations depending on the type of application, it boils down to a few elements:

‍

Title

An ideal title is clear, short, and gives the developer a summary of what the bug is. It should contain the category of the bug or the component of the app where the bug occurred (e.g. Cart, UI, etc.) and the action or circumstances it occurred under. A clear title makes the report easy to find for the developer in order to identify duplicate reports and makes triaging bugs a whole lot easier.

E.g. [Profile] Profile picture blacked out when inside a chat.

‍

Severity and Priority

Severity is a measure of how serious an issue is. The levels and definitions of severity vary between developers of different applications and even more so between developers, testers, and end users who are unaware of these details. The usual classification is:

• Critical/Blocker: This is reserved for issues that make the application unusable or cause serious data loss.
• High: When the bug effects a major feature and there is no workaround or the available workaround is very complex.
• Medium: The bug effects a minor feature or effects a major feature but has an easy enough workaround to not cause any major inconvenience.
• Low: This is used for bugs that don't significantly effect the user experience, like minor visual bugs.

‍

Description

This is an overview of the bug and how and when it happened, written in shorthand. This part should include more details than the title, like how frequently the bug appears if it is an intermittent error and the circumstances that seem to trigger it.

‍

Environment

Apps can have completely different behavior depending on their environment. This part should include all the details about the environment setup and configuration on which the app is running. If you require specific info about the environment, make sure that is clear to your users and testers.

• Device manufacturer and model number
• OS
• OS version
• Application version
• Network connectivity
• Battery state
• Screen orientation

‍

Repro steps

This should include the minimum steps needed to reproduce the bug. Ideally, the steps should be short, simple, and can be followed by anybody. With that being said, encourage your testers and users to submit too many details rather than too little. The goal is to allow the developer to reproduce the bug on their side to get a better idea of what might be going wrong. A bug report without repro steps is minimally useful and only serves to waste time and effort that can be dedicated to resolving more detailed reports; be sure to communicate that to your testers and in a way that makes sense to your end users.

Example:

• Launch App > Messages > New Message.
• Enter recipient and message but leave "Subject" blank.
• Tap Attach > Image and choose ABC.jpeg (attached to report)
• Tap Send

‍

Actual Result

This is the result or output that the tester or user observed.

Example:

Error displayed: "Invalid format"

‍

Expected Result

This is the result or output that was expected or intended.

Example:

.jpeg format supported and message is sent with empty "No Subject"

‍

Attachments

Attachments can be very helpful for the developer to pinpoint the issue quicker; a screenshot of the issue does a lot of explaining, especially when the issue is visual. Other extremely useful attachments like logs can, at the very least, point the developer in the right direction.

‍

Contact Details

An e-mail address where you can reach the user submitting the bug should be provided in case any further details are needed about the issue. Getting the user to respond to the e-mails can be a challenge so you should consider providing other communication channels that are less of a hassle to the user to maximize their responsiveness.

‍

‍

• DO read your report when you're done. Make sure it is clear, concise and easy to follow.
• DO be as specific as possible and don't leave room for ambiguity.
• DO reproduce the bug a few times and try to eliminate any unnecessary steps.
• If you have found a workaround or additional steps that make the bug behave differently, DO include that in your report.
• DO check if the bug has already been submitted. If it has, add your details to the bug in a comment.

‍

‍

• DON'T include more than one bug in your report. Tracking the progress and dependencies of individual bugs becomes an issue when there are several bugs in the report.
• DON'T be critical or blaming. Bugs are inevitable and not always easy to fix.
• DON'T speculate on what's causing the bug. This can send the developer on a wild goose chase, so stick to the facts.
• DON'T post anything that is not a bug. Developers love to hear your feedback, but posting it in the wrong channel will only clutter their workflow and cause unnecessary delays.

‍

‍

• Educate your testers or users on how to write a bug report.
• If you're collecting bug reports for a beta test, clearly define the objectives of your test.
• Use a feedback channel to communicate constantly with your testers and users in order to keep them engaged and let them know that their feedback was received.

‍

Most good beta tests involve a tool like Instabug's Bug Reporting that automates these reports and makes it easier for testers to communicate with developers and provide feedback, while an in-app feedback tool for live apps offers an intuitive channel for end users to report issues. A bug reporting tool captures all the technical details you need automatically without extra time or effort from you or your testers or users, and without losing any precious data.