The fundamentals of effective bug reporting
Updated: Mar 3, 2022
There is no dispute about the importance of writing an effective bug report; it's the primary key to the success of any Bug life cycle (BLC). Effective bug reports should base on a few fundamentals that I will cover during this article.
Why are effective bug reports so crucial in the Bug life cycle? I know that you already know the answer; if not, review this list:
Effective bug reports will increase communication among team members.
Effective bug reports will increase the chances that the bug gets fixed.
Effective bug reports will reduce the programmer's investigation time.
Effective bug reports will validate that the bug contains all the necessary information that will help during the fixing and verification process.
Bug reporting general guidelines
There are some basic guidelines that we must follow to make the bug report as efficient as possible:
Isolate the bug, make sure that you identify precisely what the problem is (Root Cause).
Please keep it simple and do not exaggerate. You are not writing an article or crime report.
Ensure that the bug report describes one specific bug (One bug = one report).
Before opening the bug, validate that the bug does not already exist in the system.
Make sure that you use technical facts and not personal opinions.
Do not use abusive language; remember that you and the developer have the same goal.
The bug reporting Mandatory fields
Bug Title
Once the bug is opened, the title becomes the first thing other engineers will see. As a result, the bug title should be meaningful, descriptive, and unique (usually built from 40-60 characters) in a way that will allow them to understand what the bug is without the need to read the full bug description.
Bug Description
The bug description is the area that should extend the information about the bug based on the bug title, including many artifacts such as:
How this bug will affect the system.
Expected Vs. Actual results.
The environment variables
Description of the bug.
Reproduction scenario.
There are a few simple guidelines that we can use to validate that the bug description is suitable for the exactable quality standards:
Make sure that the description reflects the actual and entire picture.
Describe the bug without any exaggeration.
Don’t use inappropriate language.
Don’t add irrelevant information.
Use straightforward language.
Reproduction scenario
A bug incident must include clear instructions on how to reproduce the problem so that others can reproduce it without the need to ask numerous questions.
A good incident report will include detailed information about the different phases that the programmer can follow to reproduce the bug, and each step should consist of the relevant details and nothing more; remember that we do not need to write stories, just the MIN necessary information that will help others to reproduce the bug.
So how can you write a good reproduction scenario?
The reproduction flow must be clear.
The reproduction flow must be informative.
The reproduction flow must trigger the bug.
The reproduction flow should not include irrelevant steps.
The reproduction flow must be tested before adding it.
The reproduction flow must include a prerequisite list (Test Environment, Testing data...).
Determine the reproduction availability
Can you reproduce this bug?
How much time does it take to reproduce this bug?
Is this bug reproduced in the specific lab?
Is this bug reproduced in different environments?
Is this bug existing on older versions?
Details about the version and build
The bug report should include the project's name, iteration, and the exact build number that the bug was found on.
Environment Details
This section should add some background information about the test environment used when the bug was found. The minimum information should include the Device type, operating system, platform, and setup configuration.
Bug Severity
The severity of the bug will help determine how severely the bug is in terms of damaging and affecting the system. For more information about bug "Severity," please read my previous article:
https://www.agilequalitymadeeasy.com/post/how-to-determine-your-bug-s-severity
Bug priority
Determined by the team/project manager, and therefore I will exclude it from my review, but if you need more information, you can use this link:
https://www.agilequalitymadeeasy.com/post/how-to-determine-your-bug-s-priority
The Expected results
Remember, when you report a bug, you describe an error or deviation from the system's predefined requirements. In this section, you need to describe the accurate way that the application should work.
Also, we must add the expected results based on documentation and NOT on your personal opinion; otherwise, the developer will follow your argument and fix the bug against the actual requirements.
The Actual results
This section will describe the actual results that we got based on the reproduction scenario/or on any case that we want to report, although we don’t know the exact steps that cause it.