By Gaurav Singh

As a tester/developer, once you find a bug in the system under test, the logical step is to either fix it (if it’s really that small 😉) or to write a bug in the bug tracking system of your choice. This allows yourself or your colleagues to take a look and fix the issue.

A well written bug report is an unsung saviour that saves all involved stakeholders from a possible headache-inducing ordeal.

TL;DR: If you are looking for a bug report template to follow in your projects, here’s one I came up with, after being inspired by other testers and a few open-source projects. Of course, feel free to modify the template based on relevance to your context.

Bug template to help in writing clear bug reports

Bug template to help in writing clear bug reports. GitHub Gist: instantly share code, notes, and snippets.

Gist262588213843476

Let’s get into the particulars of what constitutes a good bug report and tips on how to come up with them:

Include all the necessary details 🔍

Bugs logged in a system are often written in a hurry with less attention to detail. In most cases, they are probably just a one-liner title.

This can lead to a lot of confusion for the person who would be referring to it next because important details may not be captured, and having to put on their Sherlock Holmes hat and searching for answers is quite a frustrating experience. 🕵️‍♂️

This often leads to a back-and-forth between developers/testers/product managers while figuring out the area the issue is present.

Some common questions that a person asks, when trying to fix a bug in a typical consumer or a business facing app for web/mobile/backend systems, are mostly along the lines of:

When does this bug occur? How can it be reproduced?

What is the buggy behaviour and what was expected?

What is the impact on the user? How critical it is to fix? Does the fix need to happen now or later?

Does this happen with specific test data only?

What build was used to test this? (Ideally tagged to a git commit)

If the bug is on mobile, then what was the mobile, viewport size, and OS details?

If the bug is on a browser, then what is the browser type, resolution, version?

If the bug is in an API then which specific API/business flow is impacted, and what are the request params and response?

Screenshot with a marked up area which is buggy.

Video showing the steps to arrive at the bug.

Application/Server logs?

Any specific feature toggle/configuration that was in play when the bug occurred?

and many more depending on the context. Yes, many more. 😅

Moral responsibility as a bug advocate ⚖️

I would suggest that you should aim to give as many details as possible in your bugs, limited only by the time available/context, and to always do a bit of upfront analysis before raising a bug.

Doing this sets you up to act as a strong advocate for a bug fix and reduce the overall concern everyone would have about the issue.

A bug with minimal details is probably going to be pushed further down the Product Backlog and sit in oblivion being ignored because neither the PM nor the developer would be able to understand what the issue is or analyse further.

And we don’t want that now, do we?

The devil is in the details.

Tips for writing good bug reports 💬

Now that we have established the need for writing clear bug reports, here is some good-intentioned bit of advice, with some specifics on what you can do better the next time you write a bug report.

Take a deep breath first and start investigating

When you see an obvious bug in the system, the typical knee jerk reaction from a tester/developer is, “What was the person who developed this thinking?”, “This is really silly, how could they have missed this in their unit/integration tests?”… yada yada.

Yes, we’ve all been through this during our careers. But, I urge you to take a moment and a deep breath and calm down first.

What one should understand and realize is that most commonly a bug manifests itself at different layers of the stack and under specific conditions, which could comprise of multiple factors.

All of those conditions cannot be simulated at a unit/integration level. Sometimes, the developer is under high pressure to release the feature within a deadline and as such tests only the bare minimum functionality.

“It’s human to make mistakes and some of us are more human than others.” — Ashleigh Brilliant

We should understand the human factor at play here and try to separate the individual from the buggy behavior.

With that little bit of empathy, the next step is to gather more evidence along the lines of the necessary details mentioned above and draft them in your bug report. Remember: It’s perfectly okay to edit and revise with more details as you investigate further.

Let’s take an example of an investigation flow:

If the bug is on a UI (app/browser), ask yourself if this is purely a presentation issue on the UI, or is it because of a bug in the business logic with the underlying API. Think about what and how you can check to find a root cause for this.

Open up the network tab on chrome dev tools if a browser or a suitable proxy tool like Charles/MITM, to view the network calls made and see whether more information can be gathered.

• Check if an API call made with the correct request parameters (URL, Header, Query, Body).
• Check if a response comes back in time.
• Inspect the response data for any incorrectness in the status codes/response body.
• Inspect the relevant database tables to see if any incorrect data was written (if needed).
• Check the application logs for the backend system.
• Check if the service is really up and going through a deployment.
• Check if a dependant service failed.

In conclusion…

It’s often quite useful to bucket a bug as either a frontend or backend issue, so that you can tag the relevant teams/people to look into and fix the issue.

Capture these details and doing all the above steps exposes a lot of internal nuances about the system that you are testing and makes you a better tester and product expert.

Write clear steps to reproduce

Often times, we as testers think it’s quite obvious how we arrive at this particular screen/page/business flow. But remember, what’s obvious to you might not be so for others or people who are new to the system.

Do everyone a favour and write clear steps on how to reproduce the issue. Capture some common flows as templates in your note-taking app and copy-paste them if you see repeated patterns of bugs on the screens.

Here are some details that you can add apart from repro steps to support:

• Add screenshots. Marked up the specific problem area, because a problem in the bottom right corner would not be obvious to the person reading your bug report.
• Even better, add a video to show the flow. Trust me, this is super helpful and the developers/PMs will really thank you for it.
• Provide the CURL for the API call and the response that you saw from the API, with the status code information.

This is applicable even while writing bug reports for open source projects. Creating a small project that depicts the problem and attaching it as a reference is so much better than giving an obscure description of the problem.

Provide version/build details/logs

Once you have done the due diligence and explained what the bug is, what the impact is, and what its priority is, you now have clear steps to reproduce the bug.

We should be all good now, right? 😌
Well, we’re almost there!

Often times, bugs are related to specific conditions like the browser, mobile, viewport, or the deployed commit/branch. Adding these details gives an extremely reliable hint about the state of the system and can point the developer in a better direction to investigate further.

For instance, in a mobile context, the bug can be happening on specific device and OS combinations and can provide a hint to the mobile developer on what specific libraries/frameworks are involved for that version.

For a backend developer, the Git commit detail could be especially useful since they can know immediately what branch was deployed on the environment and help them isolate the issue to fix. Also, providing the app logs could be helpful since most logging frameworks mention the specific application area the log is generated and could save a lot of time for the developer.

Writing clear bug descriptions makes it super easy for project members to collaborate better while triaging and fixing bugs. So the next time you see a bug, remember to write a comprehensive bug report.

If you want to add your thoughts on this topic, feel free to hit me up on twitter @automationhacks.

Happy coding and testing. 😇