Bug Reporting Basics

In this post we will be covering the basics of bug reporting. We want to make sure all users understand the importance of a well documented bug and how it can help their development team diagnose and solve problems as efficiently as possible.

I won’t get into the details of a bad bug report here but will instead focus on the format we find most helpful to us when on a bug squash. The basic template for a bug report is as follows:

When I was ______,
I noticed ______,
but the software should have ________.

PART I - LOCATION & CONTEXT

The first bit of information we want to know is what the user was doing when they ran into a problem, this will not only give us the location of the bug but also the context. Lets look at a few examples:

• When I was attempting to login into the application as a client ….
• When I was resetting my password on the forgot password screen ….
• When I was navigating to the settings page from the feed …

In the first example we know that the user had opened the app and was on the client login screen. In the second example we know the user had selected the “forgot password” option and navigated to the forgot password screen. In the third example we know the user was on the feed page and was attempting to navigate to the settings page. From all of these we are able to extract what the user was doing when the issue occurred, making it easier for us to replicate and ultimately solve the problem.

PART II - THE PROBLEM

The second piece of information we want to know is what the problem that occurred was. This will give us the results we can expect to replicate in our testing. Lets look at a few more examples:

• When I was attempting to login into the application as a client, I noticed the keyboard covers the password text field…
• When I was resetting my password on the forgot password screen, I noticed product names says a place holder name from a few months ago…
• When I was navigating to the settings page from the feed, I noticed the app crashes…

In all of the examples we now have enough information to replicate the bug on our own. In example one we know we need to be on the client login page and when we click on a text field the keyboard will cover the password text field. In the second example we know the name on the forgot password screen in an older name no longer being used. In the third example we know where the app is crashing and steps to replicate.

PART III - EXPECTATION

The third and final piece of information could be viewed as optional when looking at some use cases but if we are honest with ourselves we know that more information or context is never a bad thing. In this section we want to know what the user was expecting to happen. Lets look at some examples:

• When I was attempting to login into the application as a client, I noticed the keyboard covers the password text field, but the software should have adjusted the location of the text fields so they are not covered by the keyboard.
• When I was resetting my password on the forgot password screen, I noticed product names says a place holder name from a few months ago, but the software should have displayed the current product name.
• When I was navigating to the settings page from the feed, I noticed the app crashes, but the software should have navigated to settings page.

We now have a complete bug report that gives us all of the information we need to know where the bug occurred, what went wrong, and what was suppose to happen. From here we can easily reproduce the bug, fix it, and make sure the fix produces the expected action.

FOR FUN

Often times (usually late at night) I will get a new notification that someone has logged a bug report that follows this format. Lets review a couple of bug reports we want to avoid. Please don’t write bug reports like this:

• URGANT. MUST FIX. APP ICON COLOR IS BLUE
• APP CRASHES.
• I CANT FIND how to invite users.

These examples all have several problems with them. First they are not very descriptive, not one of these examples gives us any context into what the user was doing, what is wrong, or what would fix the issue. Second, the all caps is really not needed. There are no action items for any of them, these are all just statements.

It is important to remember that the goal of a bug report is to report an issue that the developer or project manager can easily reproduce on their own and then understand what they need to do to resolve the issue.