our insights on web development and the Drupal CMS

Three Components of a Successful Bug Report

It's inevitable that some things don't work quite right while your site is being developed. That's all part of the process - working out the kinks and making the site ready for visitors.  

Some projects have a dedicated project manager who's responsible for doing QA and testing, and delivering bug reports to developers.  But often, clients interact directly with developers over smaller issues, or on smaller projects.  In these cases, being able to write effective bug reports yourself can significantly speed up the development process. If you can clearly and succinctly explain what is not working properly, we can do our best to fix it.

The problem is that most people don't have experience writing effective bug reports.  But there is a good pattern to arrive at an effective bug report, and it has three simple components.

What went wrong

Probably the most obvious thing to include in a bug report is a description of the bug itself. Still, there are some important details about this part of the bug report that you should include.

You should be sure to clearly describe the thing that went wrong. A statement like "the page is broken" does not encompass the bug. A complete description of the problem is more helpful, such as "the sidebar appears below the main content". It doesn't need to be long, it just needs to adequately describe the issue.

This is usually the only part that most novice bug reporters include in their reports -- a description of the problem. In itself, that's a start, but there's more to it than just what went wrong.

What I did to break it

This is the best place to be detailed, because - to quote my personal motto - a bug that is not reproducible is not a bug.

If the bug is on a web page, you should include the URL of the page in the bug report.  This ensures everyone is looking at the same thing. Including just the title of the page or the name of the page may not be enough, but the URL is most accurate most of the time and should be included.

Sometimes there is a process to the bug. If you are filling out a form, you should include the URL of the form, the values that you submitted, and the button that you clicked to get the result. Be explicit! If you didn't click the Submit button on the form, and instead pressed Enter to submit the form, this is a detail in the reproduction of the bug that could make a significant difference.

Be sure that before you send your bug to the developer that you can actually use your steps to reproduce the bug. If the bug only happens intermittently when following your steps, then it will likely take much more time to sort out what additional criteria must be met to cause the bug to happen. If you can provide a set of instructions that cause the issue to happen each and every time, then it'll be much faster to arrive at a solution.

You may find that when you submit a bug, the developer will respond by saying "I can't reproduce this problem." This usually means that your steps weren't explicit enough. Try re-reading your steps carefully as if you were another person, and see if there's anything you can clarify.

What I expected to happen

This is the component that is most often lacking from a bug report, and one that can make all the difference in solving your issues in the most expedient manner possible.

Describing the problem and how to arrive at it is the first step, but if you can provide direction on what was supposed to happen, it becomes much clearer how to resolve the bug.

Sometimes this is obvious, it might not be obvious to the developer.  Many times, the bug exists in the first place because the developer misunderstood the intent of the functionality from the onset. If you describe a bug without this component, they may be thinking, "Isn't that how it's supposed to work?"

Rather than delay the debugging process with the back-and-forth conversation over this confusion, simply include a description of what is supposed to happen when you follow the steps you outlined, and everyone will be on the same page .

A short example report

A complete bug report containing all three of these components need not be multiple paragraphs, and doesn't even necessarily need to have one sentence per component. Consider the following simple report:

The URTC landing page is yellow.

This report is falls short because it doesn't provide the steps to reproduce the bug (which essentially includes the single step of viewing a particular page) and doesn't say what color the page should be. It is also unclear what yellow thing is the incorrect color.

This is a better report:

The URTC landing page at has a yellow background on the box labeled "Membership", and it should be the green from the original design.

This report is better because it is explicit about which component is the incorrect color, provides the URL of the page that shows the incorrect color, and explains what would be a correct resolution to the issue. The report is slightly longer, but the extra effort pays off in less confusion and faster resolution of the issue.

In summary

A complete bug report includes:

  1. A complete description of what is incorrect.
  2. A detailed, reproducible set of steps that another person can follow to see the problem.
  3. A description of what is supposed to happen instead.

Be sure to include all three of these components in any bug report you submit to your developer, and your project and communication with the developer will improve dramatically.