Timely and effective troubleshooting hinges on the quality of the bug report. Unlike email threads, bug reports serve as a single source of information for describing the issue, eliminating the friction between team members and promoting quicker fixes.
It may seem like writing a bug report is no big deal, but in reality, not all testers can deliver a bug description in a clear, structured format and make it easy for the developers to reproduce and understand the bug. In this article, we will share our time-tested approach to writing bug reports along with actionable tips and a ready-to-use template.
What is a bug report?
A bug – is an error, flaw, or fault in a computer program or system that causes it to produce an incorrect or unexpected result or to behave in unintended ways.
No wonder, bugs are a real pain for every project. They can lead to various problems, such as delayed app release, failed marketing campaigns, damaged reputation, and even cause the failure of the entire project.
A bug report is a technical document that contains all the necessary information about the bug and the conditions under which it can be reproduced. It is a guide for the developers and the team that performs bug fixes.
Everyone can write a bug report, but is every bug report effective? Our QA team writes detailed bug reports, which allows the entire team to release projects successfully. With a good bug report at hand, developers can understand the steps, reproduce the bug, and compare expected and actual results.
Check out the other testing documentation at Orangesoft in our article on the mobile app testing process.
When does bug reporting take place and who’s involved?
Bugs can slip through the cracks at any stage of the software development process. The earlier they are found, the cheaper, faster, and less headachey they will be to fix. Bug reporting and fixing is not privy to QA engineers and testers, it’s a team effort.
QA engineers and development teams
Once QA engineers identify and report bugs, they submit a bug ticket for the development team to fix the issue. Ideally, a project management tool should automatically notify the team of the new ticket. Developers then get down to fixing the bugs while QA engineers oversee the bug reporting process and ensure proper documentation.
Project manager and client
Complex bugs often demand cross-functional collaboration and may escalate to project management. In this case, a project manager is responsible for the proper allocation of resources and coordination. The client may become a part of the process if the bug is found after the launch.
What should a bug report look like?
There are two main criteria for a well-written bug report form:
- Reproducibility. Reproducibility allows developers to see the issue first-hand, reproduce it, and identify the right approach to fixing it. Without reproducibility, bugs can remain hanging in the balance.
- Clarity and information value. The description must be as concise as possible yet informative. An extensive "essay" can only confuse the developer.
A bug report returned to the tester with the status "Can't be reproduced" or "Information required" is a total waste of time for both the tester and the developer. That is why it's crucial to provide a high-quality and well-written bug report.
We recommend using a bug tracking template pre-approved by the team. You can create it using good old Excel tables, but we recommend using dedicated bug tracking systems or bug reporting tools. Our team uses Teamwork, but you can choose whatever floats your boat, such as Jira, Trello, Mantis, and Redmine.
What information should your bug report contain?
Your software bug report template can differ based on the bug tracking software. However, the following fields are mandatory when reporting bugs in any system:
- Title
- Severity/Priority
- Description
- Environment
- Steps to reproduce
- Expected result
- Actual result
- Attachments (screenshots, videos, text)
In addition to the required bug reporting fields, you can add more project-specific details or nuances based on developer and product owner preferences.
- Unique report number (ID)
Each bug report must have a unique identifier. It usually consists of the first letters of the project’s title and a serial number. Most bug tracking systems automatically assign an ID to each bug.
- Author
Most bug tracking systems have this information by default, so you can quickly contact the tester who found and described the bug.
- Assigned to
This section specifies the information about the developer responsible for fixing the bug. Depending on the project's agreements and organization, the bug can be assigned to a senior QA or PM who will decide which developer should fix it.
- The status that shows the current stage of the bug fixing process.
- Incident type
We believe it is essential that testers report not only Defects/Bugs but also the possible improvements that can be implemented on the project.
- Creation date
Required fields of the bug report in detail
Title
The first and most important attribute in any bug tracking system is a brief description of the problem, which allows you to quickly navigate the issue and describe it with three simple questions What? Where? When?
For example:
What? - The photo doesn't load.
Where? - In the "Profile" section.
Under what conditions? - Tap on the "Upload from gallery" button.
Bug severity and priority
At first glance, these attributes seem to be the same, but they are not. Let's have a closer look.
Bug severity
Severity describes how the defect affects the application's performance:
- Blocker. An error that causes the app to fail.
- Critical. A critical defect that causes some key functionality to fail.
- Major. A crucial error that indicates a deviation from business logic or disrupts the program but doesn't have a vital impact on the app.
- Minor. A minor defect that doesn't violate the application's functionality when tested but affects the expected result, such as a design error.
- Trivial. A bug that doesn't affect the functionality or operation of the app but can be detected visually, for example, a typo in the text.
Bug priority
Priority indicates the urgency of the reported bug and the order in which the problem should be fixed. We use the following general gradation for this:
- High. Anything that impacts the typical user flow or blocks app usage.
- Medium. Anything that negatively affects the user experience.
- Minor. All other issues (typos, missing icons, layout issues, etc.).
There are projects where bug reports contain only one attribute set by the tester. In our team, we usually use two attributes. The tester usually sets only Severity, while the senior tester or manager assigns Priority depending on the project's primary goal or the Product Owner's preference.
In any case, we recommend establishing a shared understanding of bug report criteria by involving the entire team in defining necessary attributes and severity levels.
Description
This part describes the problem in more detail and specifies additional conditions, such as how often the error occurs, whether the error is accidental, and the circumstances that could cause it. The description should be informative yet to the point, stating exactly what is happening.
For example:
NOTE: the Account time zone = Atlantic Time (Canada)
In some bug tracking systems, such as Jira, this field also includes items such as Environment, Steps to reproduce, Expected Result, Actual Result, and even Attachments.
Environment
An application can have inconsistent behavior depending on the situation, so here you need to cover the conditions under which a bug is reproduced, for example:
- Device manufacturer and model number
- OS version
- Application version
- Network connectivity
- Screen orientation
- Browser
For example:
Device - iPhone XR.
OS version - 13.3.1.
Build version - 0.4
Connection to a Wi-Fi network
Steps to reproduce
This item should contain the minimum steps that describe the entire path of reproducing the bug. Describe one step per line. If the description requires more than 8 bullet points, you can mention them in the Preconditions section.
For example:
Precondition: the user is registered in the system.
Go to the list of products offered.
Add product "A" to the cart.
Tap on Buy.
Just keep in mind that you don't need to include obvious steps. For example, you don't need to specify: Open the app and Log in unless the problem is directly related to these actions.
Expected result
Be sure to describe the expected result according to the technical task, design, test cases outcomes, or the opinion of the tester. This way, the developer will know exactly what to focus on and won't waste their time searching for the necessary information.
For example:
Required fields are highlighted in red after clicking the" Submit" button.
Actual result
This field describes the actual effect of the bug. Sometimes testers write general statements such as The Undo Button does not work properly. This is not very informative, is it? Does the button trigger the intended action or does something unexpected happen?
It's important to write a clear description of the actual result. In most cases, it coincides with the Title.
For example:
Required fields are highlighted in green after clicking the "Submit" button.
Attachments
It is a standard practice to attach files to bug reports because visual aids make it easier to perceive information.
For example:
- Screenshot (visual indicators like circles or arrows can effectively pinpoint the bug's location),
- Video (a video is often worth a thousand words when describing a bug).
- Log-file.
Tips on writing a good bug report
A bug report can still be hard to nail, even if you have bug report templates to build upon. So here are our additional recommendations for writing an effective bug report:
- Don't be afraid to ask the Project Manager for help if something is unclear to you.
- Be sure to request feedback and suggestions from developers about your bug reports. Each project is unique, each developer is different, and it is crucial to find the right approach. A comfortable atmosphere and mutual understanding between the team members contribute to fast, high-quality work.
- Double-check before sending the bug report.
- Make sure that the bug report contains the description of only one error, not multiple bugs.
- Go over the error a few more times, correct the steps, and add more details if necessary.
- Don't criticize or point an accusing finger at your colleagues. Mistakes are unavoidable, and they are not always easy to catch or fix. Remember, you are a team!
We hope that our recommendations will help you improve the quality of your bug reports and foster collaboration within your development team.
About Orangesoft
Orangesoft is a healthcare development company that enables funded startups to deliver exceptional web and mobile experiences. As a tech partner, we help companies perform and scale app testing and QA services to promote a higher quality of the deliverables. Our team provides a set of flexible, scalable, and on-demand testing services, including regression testing, usability testing, localization testing, payments testing, and other testing services. Contact us to discuss your project and your testing needs.
