Loading...

What Makes a Great Bug Report?

What is a Bug?

To quote Wikipedia:

A software bug is an error, flaw, failure, or fault in a computer program or system that causes it to produce an incorrect or unexpected result or to behave in unintended ways.

Bugs on websites can manifest in several ways, including (but not limited to):

  • Pages which fail to load (either the whole page or parts of the page)
  • Broken links
  • Error messages appearing when taking actions
  • Calculations are not correct
  • Poor performance / slow speed

Whenever this happens, it's important to notify your development team and provide them with enough information to pinpoint the issue.

Expected vs. Actual Behavior

The very first thing you should identify is the expected versus actual behavior. Define the action you were trying to take, how you thought the system should have handled it, and what the system actually did instead.

This information helps to narrow the developer's focus to a particular part of the codebase, allowing them to debug it quicker. It can also help to identify usability issues and/or gaps in functionality where some action may not actually be supported (even if it appears to be).

Here's a perfect example of what this might look like:

I expect to be able to increase the quantity of an item in my shopping cart. However, the system does not appear to save the new quantity.

Replication Steps

Step-by-step instructions on how to recreate the issue are extremely valuable. They tell the developer exactly what process you went through to trigger the underlying issue. A developer can then repeat those steps in a controlled development environment with all of their debugging tools.

Here's an example of what those steps might look like in your bug report:

  1. Add a customizable product to the shopping cart
  2. Navigate to the cart page
  3. Attempt to increase the quantity from 1 to 2
  4. Reload the cart page and see that the quantity is set to 1

Also, be sure to note anything that doesn't trigger the issue. Using the previous example, the reporter might add notes like these:

  • The issue does not occur for simple, non-configurable products
  • The issue does not occur on my iPhone

This additional information provides vital clues on where the bug may exist.

Error Messages

To some users an error message simply means that something went wrong. However, error messages actually have very specific meanings which point to where the trouble might be.

Some error messages might be vague, like <code>connection timed out</code> or <code>internal server error</code>. Others might be more detailed, like <code>connection to api.example.com failed with a 503 error code</code>.

Additionally, even the most vague-sounding error messages are actually very unique! This is because computers don't think up error messages on-the-fly - the messages themselves are predefined by programmers. Because they're defined somewhere in code, a developer can easily search for that exact text to determine which system components are programmed to show that exact message. From there it's simply a matter of tracing backwards.

Next time you encounter an error message, make sure to include the full text of that message.

Screenshots

Taking a full screenshot of your browser window is also extremely helpful. This provides developers with several key pieces of information:

  • The browser and operating system you're using
  • The URL of the page
  • Whether you are logged in
  • The values of any form inputs
  • Any browser extensions which might interfere with the webpage

This information is especially valuable if you're unable to determine the replication steps, as it gives developers clues into what might be triggering the issue.

Date & Time

Lastly, your error report should include the date and time when the issue occurred. Developers and IT staff can cross-reference that date with internal system logs to locate other useful bits of information about what the system was doing at the time.

Summary

Providing clear bug reports to developers helps them to quickly confirm, identify, and resolve issues you may be facing. The more information you provide the better! So the next time you encounter an issue or error message, be sure to provide this valuable information.