How to Write a Good Bug Report
When it comes to documentation writing, there is a universal rule you can use: make it simple. The simpler, the better.
However, simple doesn’t mean short. Bug reports should feature the details that let a reader understand the nature of a defect. In other words, there should be enough information to see how the described behavior is a bug and reproduce it.
Meanwhile, you should avoid any extras that don’t add new information to what’s already been written.
So what does ‘good’ stand for? We can say a bug report is efficient if:
- a defect has a specified unique number assigned to it;
- this defect is reproducible, not a one-time occurrence;
- a description is specific and covers only one issue.
Don’t try to use bug reports as incriminating evidence that someone has made a mistake. Use meaningful information and avoid harsh wording. Always check your writing before you submit it.
Make sure to recreate a defect two or three times before you start documenting it. Don’t include more than one defect in your report. Finally, before you report a new bug, make sure it doesn’t appear on the list of known defects yet to avoid duplicates.
Bug Report Structure
If you are looking for a bug report example, we’ll recommend starting with theory – namely, with a list of things a bug report should feature. To provide a document that will be helpful for a client’s team, our software testers include the following information in their bug reports:
-
Summary.
-
Product.
-
Platform.
-
Status.
-
Priority.
-
Severity.
-
Preconditions.
-
Steps to reproduce.
-
Actual result.
-
Expected result.
-
Attachments.
You can use this list as a plan for your own bug report. Below, we’ll provide a brief explanation of every point.
1. Summary
A summary is a short description of an error. Ideally, it should answer three questions: what, where, and when. For example: (what?) Console Error appears (where?) on the Statistics tab (when?) after a user clicks the Download button.
Sometimes, however, you can skip the where part. For example: an application crashes after a user clicks the Sign In button. You can specify the page where it happens or skip this part if there is only one place to find the form and the mention of it is self-explaining.
2. Product
This part usually indicates a version of a build under test that features a bug you are describing. A QA specialist provides this information so that a developer can compare the latest tested version of a product with a previous one and see what has changed. It makes it much easier to identify what caused the defect.
3. Platform
A software tester should mention on what platform the defect appears. For desktop projects, we indicate an operating system. For web projects, it is browser information that matters the most. As for mobile projects, a QA specialist should indicate a device model and a version of an operating system it uses.
4. Status
A bug status keeps all members of the development team updated on the bug fixing process. The status lets you know whether a developer has accepted the bug, whether it has been sent for retesting, fixed and closed, etc. The variety of statuses depends on the workflow a team uses.
5. Priority
Bug priority shows how critical the defect is for the business and determines the order of fixing. Usually, a Product Manager, a Product Owner, or a Team Lead assigns the priority.
There are three levels of priority:
- P1 – High: needs to be fixed immediately.
- P2 – Medium: needs to be fixed after high-priority defects.
- P3 – Low: fixed in the last instant, after there are no P1 and P2 defects left.
6. Severity
Unlike the priority, the severity is assigned by a software tester based on how dangerous a bug is for the system, to what extent it affects the critical functionality, etc.
- S1 – Blockers: it is impossible to use an app due to the defect.
- S2 – Critical: a defect blocks a part of the functionality, but there is an alternative way to use it.
- S3 – Major: a defect affects a part of the functionality, so that a feature works, but not correctly.
- S4 – Minor: a defect doesn’t interfere with the core functionality, but rather with UI/UI aspects.
- S5 – Trivial: a defect has a minimal impact on the overall functionality or performance of a software product, like a misspelled word or a grammatical error.
Bug Severity vs Priority, or How to Manage Defect Fixing
7. Preconditions
Preconditions describe the necessary actions or parameters to execute or meet before executing the steps that let you recreate a defect. No particular format is required for this description, just make sure to keep the list and order logical.
8. Steps to Reproduce
The best way to describe the steps is to provide a numbered list with the sequence of user actions that end with discovering a defect. Use simple sentences to suggest what to do next. For example:
- A user opens the Statistics tab.
- The user clicks on the Save button.
- The user refreshes the page.
- … and so on.
9. Actual Result
An actual result is a problem that happens after a person follows the steps mentioned above. Describe the result using the rule mentioned in the summary, stating what happened, where, and when. It will help a developer understand what the problem is. Besides, such concise and accurate descriptions will also be useful for a QA team in the future.
10. Expected Result
In this paragraph, describe an expected outcome of the listed steps – in other words, how the application is expected to behave. That’s why an expected result can imply an error – in case a QA engineer checks a negative scenario. For example, if a user enters incorrect credentials, they cannot sign in to the system and see an error message.
11. Attachments
Attachments are extras that can come in a bug report. It is often easier to reproduce a defect using visual guidelines, especially if it is complicated to describe the steps or the result verbally. Screenshots or short videos attached to the textual description help to prevent any misunderstanding. Just remember that visual materials should be relevant and clear.
Bottom Line
It is important to create the documentation other team members can understand and use easily. Besides, it can save a lot of time and effort in the future, when the project grows and new members join the team. Now, you know how to write a bug report in manual testing. Even more than that: you know how to create a report the developers will enjoy. So save the bug report outline and make good use of it. 😉
