Writing Better Bug Tickets
Writing tickets is an art and craft. That's why we named this article The Art of Bug Reporting.
Let’s admit it - finding bugs is just the first step to having them fixed. Before developers even start their work they need to see tickets. And this is where problems begin, as some people fail at bug reporting. Their tickets sometimes tend to be written in a very “unfriendly” way.
It’s not uncommon to see tickets that only their original creators understand (or, even worse, nobody).
This ultimately leads to some unnecessary conversations or arguments during which both sides have to go through the ticket again, thus wasting valuable time and resources. All of this can be prevented by just paying attention to how you report bugs and improvements.
Consider this article your “go-to” when you decide to create a new ticket.
Before we get to the template that we follow at Apphawks, here’s a piece of a general advice: whenever you feel it’s necessary to add more details - do it. Unless it’s a trivial bug (e.g. some typo or something else of similar severity), then try to deliver as much information as it is possible.
This will make your developers’ work A LOT easier, as they won’t have to ask you about everything.
But remember - the main idea of proper bug reporting is for a person that never saw the app before to know exactly what to do upon reading your report. Don’t overcomplicate. Simplicity is the key.
And here is the template our QAs follow. Don’t worry, I will explain everything further in the article:
A proper bug report should consist of:
- Steps to reproduce
- Expected outcome
- Actual outcome
- Additional information
Now let’s dive deeper into each one of these, shall we?
This is the very first thing everyone sees in the backlog, even before opening the ticket and getting into its details. It should deliver all the necessary information using just proper keywords. Don’t get too minimalistic, though - writing too little may lead to some unwanted confusion with a similar ticket (if such was or will be created).
Here is an example of an improper title:
User unable to checkout
Ok, we can see that something is seriously wrong here, because a major functionality fails to work. But what does it mean that “user is unable to checkout”? Is any step broken? Can user even begin the process? There are very little details mentioned to even understand the severity of this bug.
Here is an example of a proper title:
User can’t finish checkout due to error 503
This is a lot better. Now we can see that the problem is at the end of the checkout, we also pinpointed the exact problem the user faces. This can obviously be extended, though this will happen in the ticket itself, not in the title.
Sometimes overlooked, this is a very important piece of information for the developer to reproduce a bug. In some cases the bug may be present on one device and not on the other.
If you’re testing a desktop app, then at least write down your operating system’s name and its version (i.e. macOS 10.15.2), if you’re on a mobile - operating system and its version together with the device (you may split it into two separate elements).
If it’s a browser - say what browser it is and its version. Not adding this detail can lead to a lot of time being wasted on trying to reproduce this bug on a wrong device or browser.
While some unwanted behavior can occur without any special “preparation”, some of the bugs only show up under certain circumstances or after certain actions.
Such prerequisite may be, for example, just finishing some other action, visiting a certain screen, being logged in or using the app as a guest.
It’s a very important detail to include, as the same bug may not show up for a guest user, while at the same time it may be bothering each user that is logged in.
An example of real-life ticket, source: Apphawks
Steps to reproduce
Single-handedly one of the most important things to mention in your ticket - an instruction on how to reproduce your bug.
Remember - other people may or may have not used the app before. Assume the latter and make these steps easy to understand. Keep them short though - adding too much information will more likely confuse the readers rather than actually help them.
Don’t get super descriptive, but don’t get too minimalistic as well. Remember about the Golden mean.
This is the behavior you expect from the app, what it should do after executing all the actions mentioned before.
For example, if your step says “Click Add to cart button” then your expected outcome will be something like this:
Item is added to cart, button’s text changed to "Remove item from cart", cart counter is updated.
A minor detail to remember about here is to write it as “this happens” instead of “this should happen”.
Similar to “Expected outcome” mentioned above, here you just write down what actually happened. Based on our example we could say something like this:
Item was added to cart, but counter has not updated, button did not change.
If necessary, both of these can be placed between steps to reproduce (for example, if the bug is more complicated).
Remember what I said before we started going through this template?
If not, here’s a reminder: “whenever you feel it’s necessary to add more details - do it”. This is exactly what this part is about - perhaps it’s worth mentioning if this bug is related to some other bug or a feature, maybe you could add an information about the impact it has on the app.
Or maybe you think you pinpointed possible lines of code responsible for this bug? Every piece of additional information helps. While not completely mandatory, it’s a nice addition to your ticket.
You may be a Shakespeare of ticket writing, but there is always a risk of someone not understanding clearly (or at all) what you’re trying to say.
Either that or your bug may be hard to describe and/or requiring something else to better explain what’s going on. Adding a screenshot (or a video, if necessary) is always a good idea.
Just remember to clearly mark the unwanted behavior - you don’t want your developers spending half of their time trying to understand the ticket and the other half - the movie or the screenshot you attached, do you?
While not mentioned in the template, I think it’s a good addition to the ticket. For example, some bug reporting tools (JIRA, YouTrack) allow you to refer tickets to each other (e.g. link some bug to the feature it was introduced in, link the ticket with a similar behavior etc.. Some tools also allow you to choose the type of ticket (Epic, Story, Improvement, Bug) or add proper labels for more information upon creation.
Now that you know how to report a ticket properly, let’s take a look at these two examples. For the sake of simplicity, I’ll mark sections [TITLE] and [DESCRIPTION] like this.
Broken log in option
Despite typing correct data I can’t log in.
Ouch. This ticket doesn’t tell us a lot, does it? You can say it's "bug reporting done wrong". We only know that logging in is broken, but nothing more. We have no clue what actually happens, what may be the case. Surely some more details can be introduced, so let’s take a look at the improved example below.
Logging in doesn’t work on Chrome, console shows error 400
Browser: Google Chrome 78
Prerequisites: User not logged in
Steps to reproduce:
1. Click “Register/Log In” button.
Expected and actual outcome at this point: User sees a modal with “Username” and “Password” input fields and a “Log in” button below them.
2. Type your login data.
3. Click “Log In” button.
Expected outcome: User is redirected to the page one was previously on (e.g. homepage), “Register/Log In” button switched to clickable “[username]” text.
Actual outcome: Upon clicking the “Log In” button page refreshes, above the form there is a text saying “Something went wrong. Please try again.”, console logs error 400.
There was a very similar bug while user was trying to register to the app a while ago, it was reported in [ticket reference here]. No other browser is affected.
This is a lot better, isn’t it?
The title alone tells you that the problem exists only on Google Chrome and what error is thrown. Upon reading the ticket you can clearly see what has to be done to retest it, you can see the expected and the actual outcome.
The additional information provided also helps with figuring out what went wrong. There is no media, as it’s not really necessary (though adding it wouldn’t be a bad idea). This ticket is very descriptive, yet not too long at the same time. A fine quality work.
And this is exactly the type of tickets we create at Apphawks. We care about the quality of the software just as much as we care about the quality of tickets, we're no strangers to proper bug reporting. With us on board you no longer have to worry about any problems with your app, as we got you covered!