How to write an effective bug report

One of the most basic skills anyone dealing with software needs, especially testers, is the ability to write an effective bug report. I’m sure when you first see “bug report” you think it only matters for testers but, trust me, this skill is a very necessary skill for just about everyone. Unfortunately, it’s also a skill that is either undeveloped or underdeveloped in probably 90% of the people I deal with, even technical professionals. Sad but true. I place a lot of the blame for this lack of knowledge and skill on the fact that no one ever seems to teach what a good bug report should contain.

After encountering yet more “bug reports” in my bug database at work today that were completely unactionable because they didn’t include even the most basic information I needed to have in order to start investigations, I decided to publish my own little guide to effective bug reports.

Note that there are multiple pseudonyms for “bug” in use around the industry but I’m just keeping it simple here. Use whatever pseudonym makes you happy. Also note that there are many, many ways of tracking bug reports and a lot of them require that the person filing the bug report fill out information in addition to what I have talked about below. This varies so much by system, team, etc. that I can’t cover them all, but the basics listed below will get you 90% of the way to a useful, actionable, clear bug report. I’m not going to address severity, priority, etc. as those are constructs put on top of bug reports in order to further classify them.

The Purpose of a Bug Report

The purpose of a bug report is to give as much information on a bug as necessary to allow the bug report recipient to investigate the issue and help you to resolve it. That’s it, really, but what I consistently see people doing is forgetting that phrase “as much information on a bug as necessary” and just saying something like “I tried this and it didn’t work.” or “This broke.” These are completely useless bug reports as they contain no details that would even allow someone to begin an investigation. In fact, they aren’t even bug reports – they are just complaints.

Note that I don’t say “all information” because there will be information that does not need to be in the bug report. Typically bugs are not caused by things like what material your desk is made of (as an extreme example) so you do have to exercise some filtering.

Basic Bug Information

All bug reports should include the following information, no matter how they are filed (bug database, email, contact form, etc).

Descriptive Title
The title is the first thing the investigator will see, it’s the most visible and usually one of the easiest to search for. This is your prime area for key information and to clearly state what the bug is. The title should be concise but contain any unique information that may get quick action or allow the investigator to relate your bug to other known issues or reports. Consider these two examples of bug titles:

  1. “MyApplication crashes when USB is plugged in.”
  2. “MyApplication fails with error 1234567 on MyOSv1 when MyCamera is plugged in via USB.”

Notice that the second title gives a lot more information right up front? The error code, the camera make, the OS, etc are all immediately present and can be searched for. The title concisely explains what happens, in what environment and when. You do have to work within any character limits imposed but a great title is a huge help.

Impact
There is always some argument when I tell people that I include a statement of impact in my basic bug information list but it makes a big difference in getting a bug fixed if the impact it has is clearly understood up front. Impact can be as minor as a bug that causes the screen to flicker briefly or as major as a system crash and data destruction. Think about what impact the failure itself has and then what impact the steps to recover have and clearly state them for the investigator. You may even know impacts that the investigator doesn’t but should know in order to appropriately classify and prioritize the bug.

I write impact statements like:

Impact: Unable to use MyCamera’s USB download with its OEM supplied software with MyApplication running. I have to manually quit MyApplication before plugging in MyCamera. Recovering from the MyApplication crash requires a system reboot.

Clear Repro Steps
Repro steps are what the investigator will use to try to reproduce your bug for investigation and that means they need to be correct, complete and sequential. I strongly favor these are a numbered list of instructions similar to those shown below:

Repro Steps:

  1. Start MyApplication
  2. Plug USB cable into system and MyCamera usb ports
  3. Turn camera power on.

The repro steps should be free from anything that doesn’t really pertain to the bug so, for example, unless the type of user mattered, I wouldn’t bother saying which user and what security level that user has. In software testing, a goal is always to reduce the repro steps down to the minimum needed to cause the bug to occur. If there is more than one way to get a bug to repro, then I typically use the steps for the shortest or most basic repro scenario. If you have to have a particular state before the bug will occur, that goes at the top of the Repro Steps. So you may start with something like “System needs to be freshly rebooted.” or similar.

Expected Result
Including an expected result in your bug report will help the investigator to determine whether your expectations are accurate. You can be expecting something to happen that won’t because it’s not included in the design or you could be correct in your expectations. Either way, a clear statement of what you expect should always be included. To expand on the sample I started with, I’d include an expected result of:

Expected Result: MyCamera software will autolaunch and I will be asked if I want to download the pictures off MyCamera.

Actual Result
This is where you state what actually happened in as much detail as you can. Just like in the title, this is not the place for “it crashed” but rather a place to tell the investigator whatever you can about what happened when the bug occurred.

Actual Result: MyApplication crashed with a Windows error 1234567. MyCamera software never launched and MyCamera was listed as an unrecognized device.

Each part of this result can give the investigator a clue as to what happened, so they are all worth including. Even if what happens is as seemingly simple as “no device was recognized” or “software did not autolaunch”, you should always have this Actual Result section.

Environment Information
This is an area for you to list the specifics of the environment in which the bug occurred. How much detail you go into depends on what you are reporting a bug on, but some of the common ones are:

Environment:

  • Operating System and Version
  • Processor Architecture
  • Affected Product Versions and Build #s
  • Browser and Version

If your bug has nothing to do with a browser, you probably don’t need to list the browser. You may need to add in specific information that matter to your particular bug like hardware versions, drivers, etc.

Notes
The last section I always have as part of my Basic Bug Information is a section for notes. This is the place to list whatever solutions you’ve tried and what happened, a place to list if the bug occurs when a different repro step set is carried out. You can list any guesses as to what might be causing it to help out the investigator. If you have any log files, screenshots, etc, you should indicate so here and attach them if you have a way to do so. If there is no way to attach them, indicate you have them available if needed. If you have discovered your bug only occurs if you do things one way but not a very similar but different way, indicate that here. Try to make it as easy to read and understand as possible and break it into coherent paragraphs.

Summary

Writing an effective bug report is a skill everyone should develop to some extent but it’s critical for software professionals.

Below is a quick snapshot of my Basic Bug Information list that I’ve used in software testing for more than a decade and still use as a technical writer. I’m formatting it as code so you should be able to copy and paste it easily.


Title:

Impact:

Repro Steps:
1.
2.
3.

Expected Result:

Actual Result:

Environment:

Notes:

Tags: , ,

Leave a Reply