Test-42’s guide to logging bugs

Posted on Posted in Guides

Introduction

As a software tester, writing bugs is a pretty big part of our working lives. Whether you’re logging them via a bug-tracking tool, Slack, email or just screaming them aggressively across the office, there are always key pieces of information that enable us to prioritise, resolve and retest them quicker.

When logging these bugs there is always a degree of common sense required and all projects will have extra pieces of information that will help diagnose and reproduce the issue faster (e.g. browser when testing web or phone model when testing mobile) however in this guide I will be focusing on the core information that will almost always be useful and relevant.

Example:

screenshot-at-nov-17-00-22-11

Summary/Title/Overview

summary

The key to writing a good summary is to convey only the important information in as few words as possible. The simplest way to do this is to start with the affected location/functionality, then a few words about what’s happening.

The initial piece of information gives people the context, allowing them to get an idea of the issue at a glance. Then for the second part we want to be both concise and informative, including any keywords that make the bug unique. Bear in mind that most bug-tracking tools have a search function, so have a think about what keywords you would use if you were searching for the same bug.

Good Examples:

  1. Homepage – ‘Meet The Team’ link unresponsive
  2. Reset Password – Email not received
  3. Contact Form – Not displayed on Chrome

Bad Examples:

  1. Broken link on website
  2. Unable to reset password
  3. Contact form missing

Above were good and bad examples of summaries for the same issues. The bad examples aren’t necessarily incorrect, they just don’t provide enough information to the reader.

Description

The description is probably the most important part of any bug you raise as it is here that we explain what we did, what happened, and why what happened differed from our expectation.

The cleanest way to represent this is by splitting the description into three parts; reproduction steps, outcome and expected outcome.

Reproduction Steps

stepstoreproduce

If any tester tries to claim to me that they have never had a bug sent back to them along with the two words “Cannot reproduce” then they are either a liar or practice witchcraft…I’d wager the latter.

We’ve all had it. There are various reasons for it (environment, timing etc), however a lot of the time (whether we admit it or not) it’s because the reproduction steps simply aren’t clear enough.

The easiest way to prevent this is to be as literal as possible, avoiding any assumptions. Write the steps as clearly defined directions, starting from first loading the programme, to the outcome. This way we give ourselves the best chance of being clear.

Good Example:

  1. Navigate to http://www.test-42.com/
  2. Click ‘Contact Us’
  3. Enter “Tester Testerson” into the ‘Name’ field
  4. Enter “test@test-42.com” into the ‘Email’ field
  5. Enter “01111111111” into the ‘Phone’ field
  6. Click ‘Submit’

Bad Example:

“Submit a valid phone number”

Like with the Summary’s, the bad example isn’t wrong, it just omits information that could help recreate or diagnose the issue. The important thing to remember is that the exact data you enter will probably not make any difference, but it might.

This may seem rather pedantic, but that’s kind of the point. To emphasise what I mean, here are just a few questions that could be asked of the bad example, but are all answered by the good example:

  • On what page does the issue occur?
  • What counts as a ‘valid’ phone number?
  • Were the other fields completed with valid values?
  • How was the form submitted (clicking a button, Pressing the ‘Enter’ key etc)?

If these kinds of questions are already answered in the repro steps, both the resolution and retesting speeds will likely be much faster, which benefits everyone.

Outcome

outcome

Right, well this one should be pretty simple: What is the output from the reproduction steps that you deem to be wrong or unexpected?

Like with the rest of this article, be literal, be helpful, be specific.

Examples:

  1. Validation message reads “Please complet all fields”
  2. Server error displayed (see attached for full error)
  3. User is taken to ‘Meet The Team’ page

At the end of the day, this is the simplest part of logging a bug because this part is the bug. It’s especially useful though with relevant attachments (we’ll get to that shortly) and massively more useful again when combined with…

Expected Outcome

expected

Often overlooked by a lot of testers, expected outcome can be hugely important when triaging, resolving and retesting bugs. Just because your expectations are obvious to you, it doesn’t mean they’re obvious to everyone.

For example, below are three different potential expected outcomes for the above sections first example outcome: Validation message reads “Please complet all fields”

  1. Validation message reads “Please complete all fields”
  2. Validation message reads “The following fields are mandatory and must be completed: Email, Phone, Name”
  3. No message is displayed

Depending on the expected outcome, the bug (and therefore the fix), looks very different. One is correcting a spelling mistake, the second is that the overall message itself is wrong, and the last one is that there shouldn’t be a message at all.

Without the expected outcome being defined, it may not be clear what is actually wrong with the recorded outcome.

Attachments

attachment

Whatever the bug is you’re logging, there is normally some extras you can hand over with it to help understand or reproduce the issue. And because I seem to be Captain Example so far in this article…

Examples:

  1. Screenshots
  2. Videos/Animated GIFs
  3. Error message
  4. Log files
  5. Test data e.g. upload files