How to integrate an SDK into your app
If you want to manage the bugs in your software, one of the most critical parts of the testing process is having your testers or bug reporters document any bugs they find.
In all likelihood, your team already writes bug reports but may benefit from a more unified model.
Or, they currently may not be reporting bugs at all—and bug reporting is a practice you want to include in the testing process.
This article can help you guide your team to write well-structured bug reports by showing you what a great report should look like and what information it should contain.
Table of Contents
Bug title
The bug title is the first and most basic information necessary in a bug report.
A good title will serve two purposes—quickly identifying the specific entry from a large list of bug reports and giving general information about the bug in question.
The bug title should be as short and specific as possible, relaying the most important bits of information and avoiding vagueness.
To illustrate what we mean, here’s an example of a bad and a good bug report title.
As you can see, a good title concisely summarizes the effects of the bug, while a poorly written one includes redundant information, making the title unclear and confusing.
Get unreal data to fix real issues in your app & web.
A good title helps make the bug report more efficient by clearly identifying the problem and where it’s located.
In short, when a report has a good title, developers tasked with fixing bugs can easily find it, and promptly get started on analyzing its content.
Environment specifications
The next critical piece of information a bug report should contain is the specific environment where the bug occurred.
This information is necessary because sometimes bugs appear only in specific environments.
Bug reporters should write out environmental data in each report to avoid confusion and wasted time trying to determine the specific conditions surrounding a bug.
Environment specifications can include the following pieces of information.
- Device type (hardware, device model, screen size, pixel ratio, zoom level, etc.)
- Operating system (its name and version number)
- Software version (the version of the application being tested)
- Network strength (if the bug is dependent on an internet connection)
Here’s an example of environmental specifications for a browser-based application.
| Browser | Chrome 107.0.5304.121 |
| Screen Size | 1280 x 800 |
| OS | Windows 11 22H2 |
| Software Version | 2.11 |
| Zoom Level | 100% |
Including this data in a bug report is essential for developers and testers so they can refer to it when they want to reproduce the bug and set up the correct environment for analysis.
Bug reproducibility
The next piece of information, bug reproducibility, can tell developers how often the bug has occurred by following the steps in the report.
To get the rate of reproducibility of a specific bug, the tester or bug reporter needs to try and recreate the bug multiple times and note how many times out of the total attempts the bug has appeared.
For example, testers can include this information in the report simply as reproducibility: 3/7, meaning that the bug has appeared three times out of seven tries.
Or according to this rate of occurrence, bug reproducibility can be categorized in multiple ways.
While the majority of bugs can always be replicated, there are some that only appear under very specific and elusive conditions.
However, even those types of bugs still need to be reported, so developers can properly investigate them.
Steps to reproduce
A comprehensive bug report would be incomplete without the steps to reproduce the error in question.
A bug report has to explain the bug’s discovery process and the actions an end-user may take that will reveal the bug.
While writing these steps, testers or bug reporters may be more successful if they assume that the developer doesn’t know anything about the bug and will need precise instructions on how to reproduce it.
The steps should be written as simply and clearly as possible to ensure that developers can follow them and experience the bug first-hand.
For example, these can be the steps to recreate a bug that prevents users from checking out:
1. Login with a personal account.
2. Click on Buy Now on any product.
3. Click on the Checkout button.
When explaining how to reproduce the bug, it’s important to include all the necessary steps.
If a single step is missing, no matter how minor, there is a chance that the developer won’t be able to make the bug appear or start fixing it.
Expected result
Along with the reproduction steps for the bug, the bug report should include information about the expected results of the function or feature being tested.
The expected result from using the application is the desired outcome that would have occurred if no bug was present to disrupt the tested functionality.
It’s how the software or feature is supposed to work.
Testers and bug reporters can refer to three sources for writing the expected results.
The expectations from the customers should be the primary consideration—after all, it’s their user experience we are trying to improve.
If that information isn’t available, we can use established standards for how a piece of software should look and function.
Personal analysis can also be used where testers use common sense to predict how the app should function logically.
When developers fully understand the expected result, they can gauge the extent to which the bug disrupts this outcome and get a clearer idea of how to fix the problem.
Actual result
Of course, due to the bug in question, the expected result doesn’t take place, or else there would be no need for a bug report in the first place.
The actual result is the way an app’s feature or functionality that is being tested works differently than the way it’s supposed to work.
Similar to describing the expected result, being specific is key—the person submitting the report should describe, in detail, what the bug makes the software do.
Here’s some other general advice on describing the actual result.
One best practice is to keep the description factual instead of including personal opinions and ideas about the bug.
Testers and bug reporters should try to avoid using certain emotionally-charged adjectives in their descriptions, such as: bad, wrong, inappropriate, misleading, false, funny, defective, faulty, etc.
Instead, the bug reporter should give clear and simple explanations of what’s happened with the sole purpose of helping the developer get a better idea of the problem.
Bug severity
Bugs can cause a range of problems, from minor issues and inconveniences to potentially app-crashing issues.
A bug report should document the severity of the bug following a predefined classification.
For example, you can classify severity into 5 levels.
A low-severity bug will usually revolve around user interface (UI) issues, such as broken or wrongly sized buttons that disrupt the layout of the app.
A minor severity bug doesn’t influence the core functions of the application, while a major severity one affects the software negatively on a larger scale.
You can classify a bug as critical when it affects security, causes loss of data or impacts major functions.
The most severe types of bugs are ones that cause the entire app to crash and prevent further testing until it’s addressed—these bugs can be categorized as blockers.
Bug severity tells developers how damaging the bug can potentially be to the app, so it’s one of the most important pieces of information to include in a report.
Bug priority
Once bug severity is determined, the next step is to decide its priority.
The bug reporter should always include bug priority data telling developers how urgent the bug needs to be fixed so developers can focus their efforts on high-priority issues.
Priority can be reported alongside bug severity for an even clearer picture of the kind of bug the developer will have to face.
Without prioritizing bugs, developers won’t be sure of which issues to tackle first.
Maybe they will focus on complex bugs that take a lot of time and resources to fix but which are not necessarily high priority—such is the case when app features that are rarely used don’t work.
These high-severity but low-priority bugs can distract developers from tackling high-priority issues that may be less severe and thus simpler to fix, such as UI issues.
By including priority data, testers and bug reporters can help make bug fixing more efficient for developers.
Console logs
A good bug report should contain console logs to help developers understand what happened much easier.
Console logs show developers different data that can be very helpful in debugging or troubleshooting code.
Getting logs can be trickier for beginners, but they are an essential part of any good bug report.
There are multiple ways to record console logs:
- Device built-in debugging tool (accessed by enabling developer tools on a device)
- App built-in debugging tool (some app versions made for testing include this feature)
- Third-party tools
Instead of adding console logs manually, a much more efficient way is to use an automated process through a third-party bug reporting tool like Shake.
Shake can streamline the bug reporting process by automatically creating detailed reports in mere moments.
Whether it’s a bug or an app crash, Shake can send a report with over 70 metrics, which include console logs.
An example of a report is illustrated below.
The console log data is included alongside other important info which we cover in this article such as: the bug title, personal information of the bug reporter, the environment specifications, etc.
If you want to make your bug reporting process more effective and efficient, consider using Shake for your reports.
Visual proof
Another important piece of information to include in a good bug report is visual proof of the bug.
Visual proof can include pictures or video files—for example, screenshots of the bug or a screen recording of where the bug appears.
Developers can see the bug more clearly with visual proof and get a clearer picture of the steps it took to trigger it.
While it may not encompass the entire picture, these attachments can help add on to the other data in the report.
Here’s an example of a visual representation of a bug.
The person writing the report tries to indicate that by clicking the Upgrade button, the error pointed out with the arrow appears.
With this image, the report should make it quite clear what happened to the developer so they can start fixing the bug more quickly.
The reporter’s personal information
The person who has written the bug report should include their personal and contact information in a visible place in their report.
This information may contain the following:
If you use bug reporting tools like Remoteworkly.co, GitHub, Trello, or Shake, personal information can be added automatically to bug reports—in manual bug reporting, testers need to remember to enter it by themselves.
This information can help developers that work on fixing the bug get in touch with the person who wrote the report if there is anything unclear.
Developers can sometimes have difficulty understanding a particular bug or reproduction step, or they can simply have an inquiry for the tester regarding the report.
In this case, clearly visible personal information can make it easy for developers to contact the reporter promptly and fix any issues.
Date and time
Although it may seem like trivial information that can often get left out, the date and time of when the bug report was submitted are important parts.
The report writer can save developers from frustration and delay while they check whether the report is newly submitted or is an old report that was already handled and the bug was fixed.
Very handy for handling user feedback. CTOs, devs, testers – rejoice.
Date and time data is especially useful when developers search for specific defects that were present during a particular release of the app.
It’s a part of the report that is automatically included if your team uses a bug-reporting tool like Shake, but testers and bug reporters should be careful to include it if they write reports manually.
Conclusion
A bug report is an important document that helps developers locate and fix bugs more effectively.
We hope that this article can serve as a good template to help improve the quality of any future bug reports made by your team.
The items we covered aren’t the only ones you can ask to be included in reports, and not every item needs to be included—they are only the ones which, in our opinion, are essential for an ideal report.
Feel free to change your bug reports according to your specific needs and preferences.
