How to write a professional bug report.
The differences between writing a professional bug report and writing out a note that states “X is broken” can be the difference between finding and fixing a bug or not seeing the issue at all. If you really want to get issues fixed, you'll need to write a helpful report that gives the programmers on the project the ability to find and understand the issues.
For readers who work as testers, you probably already know a little bit about how to write out a report to ensure you give yourself a good chance to get a fix since your lively hood depends on it. But even for experienced professionals this article will hopefully give more ideas to help improve those reports and help get the issues fixed.
For those of you who are not professional testers this guide will be a great way to give yourself a good chance to create a valuable report that can help you:
Impress upon your audience that there is a problem.
Give your audience the tools and information they need to find the problem.
Provide as much technical information as possible that may help point towards a solution to the problem.
These tools are valuable for anyone who works with any software, not just with creating it. When you report a bug with enough information to prompt or preempt a fix you can get rid of issues that affect your work with software faster and more accurately. If you’re not a software developer writing a good bug report can be the most efficient way that you get fixes on bugs and defects that affect you.
To get started let's look at a simple example bug report template, that will show you without any other tools what a perfectly acceptable bug report will feature, and below we'll go into more details about each part.
Environment:
Summary:
Reproduction Method (Attempts: Occurred: ): Frequency:
Expected:
Actual:
These are the basic details, to fill in these details we'll start with one simple question:
What would a developer need to know to see this problem and fix this issue?
This is the first question any tester will ask themselves when they find a new bug or issue. This question frames all of the information in your report. When you think about this critically this also means you need to remove all personal opinion from a report about a bug no matter how frustrated you are. Passing on your personal frustrations through bug reports are only going to serve to make you less likely to get a fix on the issue quickly and easily. So before you start writing up a fat juicy new bug, take a few deep breaths and place your “This is bad” “this sucks” “this is ugly” etc. thoughts directly into the garbage because those initial reactionary ideas won’t help you accomplish your goals.
First, try to think all the way through the problem, because not everyone may agree with you that it is a problem at all. You should be able to clearly define the problem as well as describe why it is a problem all backed up with strong supporting evidence, not your opinion. This will be your summary statement. A summary statement can be useful for communicating the overview of the bug’s effects and details without going too deep into information, it’s best for bug reports that might be read by project managers and others who are not in charge of fixing the issue but may need to know details about it.
Example Summary: When clicked, the “Next Step” button begins to take the user to the next screen, but never finishes and a blank white screen persists without error messages shown to the user. The white screen persists for over 5 minutes. The user can’t complete the workflow in the application.
Next you’ll need a statement of your environment. Environment is one of the most important details of a bug. Environment is encompassing of a large amount of information all of which may be pivotal in reproducing the issue. The reproduction of the bug may heavily depend on the variables of the environment it is occurring in so taking care to think through all of these variables may be what is necessary to discover the root problem causing the bug to occur.
When you’re writing up a statement of your environment you’ll need to consider as many points as possible regarding where and what technologies the application is using and interacting with while the bug is occurring. Additionally try to consider the differences in environment between where the bug is occurring and where it is not occurring when applicable as these may be the most important clues that lead to understanding of why the issue is happening and a fix.
Example Environment: DEV PC #107, Windows 8 v6.1, Mozilla Firefox v38.0 (with ad block plus plugin), MyApp v3.1 (changeset 8989)
These are lots of possible variations depending on what type of software and hardware you’re working with. However most professional bug reports are going to include at least a few descriptions of the hardware and dependent software technologies that the software in question is interacting with.
There are also a few other critical points when considering environment relating to the software’s architecture. For example what “Mode” if the software in. Some don’t have modes but some have a server and a client version, if applicable you should always include what mode or specific configuration the software is in when the bug is occurring. Additionally there can also be issues arising from authentication and user handling issues. For problems like these your environment statement should also include what type of user you logged in as, we’re you an admin will full capabilities of the entire system, or were you the lowest level user who is restricted to only the critical workflow functionality that is required to perform a user’s role with the system.
User reports although frequently lacking information can still be useful to include in the full text of the documentation. Sometimes a user is a product owner and completion of the fix requires a follow up with the owner and having their initial report on file can help inform employees associated with the bug fix as to who they should be informing or following up with questions. Occasionally other information in a user report can be valuable as well, however often times user reports are the least valuable part of a bug report, so frequently they are omitted. Either is professional, inclusion or omission, and inclusion should be decided on a case by case basis.
One thing that should almost never been omitted is a statement of frequency and a reproduction method. Frequency is a percentage of the amount of times the user attempted the reproduction method, which is expressed as “attempts”, compared to the amount of times that the issue occurred during attempts, which is expressed as “occurred”. This is how you can accurately express how often the issue occurs on the given system and configuration in your environment. This is one of the most important parts of an issue report because frequency can be a factor in the severity of an issue and can factor into the priority of a fix for a bug. This means that due to the information reported in the frequency statement this could be the top priority of the entire team, and may end up being reported to project managers, owners, or other important decision makers so ensuring accurate information here is critical.
A reproduction method is usually the most valuable piece of a bug report. When a user finds an issue in their environment the actions they performed before the issue occurs could, and usually are, critical in finding and understanding the issue. The reproduction method section of your report will include a step by step method that was performed to cause the issue to occur. In this section it is best to start at the simplest step, something that a person testing or trying to fix this issue can also start at without any question that they will at least be able to start the method. Then every single step that the user performed should be written out one by one with diligent care that all steps can be performed in the same manner. Try to name things exactly as they appear in the application, so a screen with the title “User Reports” can be the “User Reports Screen”, look carefully for text on the page to help you convey what you are looking at during the process of communicating the reproduction method. If there is not enough discernible information about the text to accurately convey a name for it, then consider adding a picture or video to the bug and make reference to it in the reproduction method. The last step of the reproduction method should be the last thing the user will perform before the issue occurs.
Example Reproduction Method: (Attempts: 5 Occurred: 4) Frequency: 80%
1. Install/Load/Login as admin/Testpass456
2. Click the “Home” button in the main navigation menu along the top to go to the home screen
3. From the home screen click “New Account” to go to the new account form
4. Fill out the form will all required details and click on “Next Step”
After listing out a reproduction method with an Attempts/Occurred based frequency assessment, you’ll need to clearly explain the discrepancy between what was expected to occur and what actually occurred in an expected statement. If your software is being built with specification documents or any design documents supporting the functionality, this is a good time to bring in that specified design and add it to the report in the expected section. If you’re just a user and don’t work with the design documents on the project, you may want to add in some rational for why you expected the application to behave in this way, to ensure you’re interests for the function are in line with the goals of the developers.
Example Expected: Per the Technical Specification Document under Home > New Account in 1.12.3 the “Next Step” button should take the user to a new screen to attach documents after filling out the form on the New account form.
Next, there is an actual statement, more novice bug reports will have this included as part of the reproduction method but it should be broken out. In this part you clearly express what actually occurred with enough detail to be precise and accurate. Often time’s precise and accurate means you’ll need to attach more information to ensure the issue is documented well. For visual or functionality bugs, this often means that a photo or video is a good addition. For issues causing a debugger error, crash or unhandled exception, a log file or trace file should usually be required.
Example Actual: The site shows a blank white page that does not resolve to any new pages after waiting for over 5 minutes on a timer. See attached video “NextBug.mp4”. Console log in Firefox shows the below 403 Forbidden error.
HTTP Error 403.14 – Forbidden - Directory listing denied. You don't have permission to access …/userapps/uploads on this server.
If you have the tools, grabbing a log file and attaching it or copying the full text into the report at the end is ideal.
Now that you've finished all of the other elements of the report, you'll want to give it a title. It's nice to give the issue a title last since you have already thought through all of the other details of the issue and can sum them up concisely a little more effectively now. For many people this may be the only part of your report that they see so ensuring that this title is clear is crucial.
Example Title: "Next Step button is inoperable, leads to blank page"
Performing these steps does not guarantee that a fix will be possible, but it does give you a great chance to have the issue recognized and solved. Sometimes when an issue with software occurs the best course of action is just documenting the problem in a clear and easy to understand way for presentation to the product owners.