Write a Bug Report Your Developer Will Love

Airnauts
7 min readJan 5, 2023
text by Adam Stolarski, visuals by Filip Dueskau

If you are part of the Web development team, you probably, at least once, have been part of this conversation:

Client or colleague: “The website doesn’t work.”

Developer: “What part?”

Client: “The main site.”

E: “Which part of the website?”

Co: “The shopping cart.”

E: “I see it just fine — what’s wrong?”

All systems fail sometimes, and it’s a tester’s responsibility to catch that so that the users never have this frustrating experience. A bug report is precisely about identifying issues to help developers debug the problem fast and with clarity, as they will know what, when, and where it is happening. Good QA will reflect mainly on the development costs as developers will spend less time investigating the issue.

A well-written bug report maintains efficient communication between developers and QA teams. Thus, a software tester’s most important skill is writing good bug reports.

How do you make a bug report that your developer will love and clients will appreciate? In this article, we will share with you some tips & tricks based on the experience of the QA team at Airnauts.

So let’s go back to our developer, who learned that something went wrong with the shopping cart. It goes something like this:

  • “I need more information.”
  • “Which environment were you testing?”
  • “Does it happen in XYZ environment as well?”
  • “Have you also tested this path?”

A “Perfect” Bug Report

Developers are very often under a tone of pressure to deliver new features and upcoming releases and solve QA bugs identified during sprints. On top, developers face two extremes: a need for more critical information or too much unnecessary information.

The more straightforward the developer’s point of view is, the better. The details in a bug report are essential — they should explain the problem. Bug reports should contain just enough information to communicate:

  • What is the problem?
  • Which part of the software is affected?
  • Where exactly can the problem be found? (component/environment)
  • How can I reproduce it, and what is the repro rate?

If you nailed down this part, you could skip adding extras that do not add value.

So what is an efficient bug report? We can tell you how we do it at Airnauts!

  • The issue has been reported as a separate unique task/bug with a unique identifier (depending on the bug tracking tool)
  • The defect is reproducible (We do not want one-timers without repro steps)
  • The description is simple and specific, and it relates only to the nature of the reported problem

Also, always before reporting a new issue, follow these four rules:

  1. Check if someone already said the bug to avoid duplicating others’ work
  2. Make sure to recreate the problem more than one time
  3. Under no circumstances report two issues in one bug report, even if they are related (link them)
  4. Do not use judgemental language in your report or assume that the developer made a mistake. The role of QA is to help and support the development process, not to judge! :wink:

What exactly stands behind the “Perfect” bug report? Let’s find out!

Bug Report Template

Before looking for screenshots of bug examples, it’s better to dig into the theory. We recommend scanning articles and papers on how to structure the bug report and what information to include. Keep in mind that there are many different ways to achieve your goal. For example, the bug report format may vary depending on the bug report tool, or the bug template might be slightly different depending on the project.

Getting to the point, our Software Testers include the following information in their bug reports:

  1. Title
  2. Summary
  3. Environment
  4. Platform
  5. Status
  6. Priority
  7. Severity
  8. Preconditions
  9. Reproduction Rate
  10. Steps to reproduce the bug
  11. Actual Result
  12. Expected result
  13. Attachments

Here’s the breakdown of the above structure:

1. A clear title

Please keep it simple, short, and specific (within 60 words or below). To create a clear title, you need only to answer these two questions so that you can identify the main issue without looking inside the description:

  • Where is the problem?
  • What is the problem?

Examples:

:x: BAD: “I can’t see the products when I want to buy them for some reason. WHY? FIX it asap!”

  • Harsh language
  • No information about when happens or where it occurs
  • Asks for a solution to be implemented

GOOD: “ Checkout / Products overview / Items from cart do not appear on the checkout page.”

  • We can see where the problem occurs
  • We can see what exactly is happening
  • As a developer, we can see only hard facts and information that is clear and concise.

2. Summary

We can add an explanation of the issue only if it is necessary and when the information will add valuable extras to the ticket. Such as

  • Console Errors that appear
  • Responses from BE that might be related to the issue
  • HTTP errors
  • An additional description of where?
  • Additional description of when precisely at which step the issue occurs

3. Environment

This information indicates the version of the build that the tester was using while testing the feature. It can be

  • Name of the git branch
  • Local/Dev/Staging/Production(or other environment name, depending on the naming convention) and its version.

The DEV team can compare the latest version of the specific branch with the master and see if any changes in the code can cause the issue.

It makes it much easier for the development team to find and debug the issue.

4. Platform

A QA Engineer should indicate on what platform the issue occurs.

Example:

  • Web project -> Browser Name & Build,
  • Desktop projects -> Operating System
  • Mobile Apps -> Device model & operating System

We can also differentiate if the issue is related to

  • Backend
  • Frontend
  • Mobile view
  • CMS/CRM or other system
  • 3rd party plugin / Integration issue

5. Status

It can vary on the project setup & workflow itself. However, the most important information here is to indicate at which level of the development the issue currently is:

  • Something that needs to be done
  • Something for Retesting
  • Something was tested and approved by the QA
  • The issue was closed

6. Priority

Many testers have trouble telling the difference between priority and severity, so let us explain what the two terms describe. To set the priority, we consider the client’s objectives (What and when needs to be done based on the sprint/clients’ goals).

The PM, PO, or TL mostly use the priority to assign and determine the order of fixing the bugs. However, sometimes you will find yourself in a position where you will be responsible for determining the priority.

Here is a brief overview of the essential priority levels.

  • P1 — High: needs to be fixed ASAP.
  • P2 — Medium: Needs to be fixed after high-priority defects
  • P3 — Low: Fixed in the last instant after there will be no P1 and P2 bugs inside the sprint left

7. Severity

A tester must be able to distinguish the severity of the error, as some might impact clients’ revenue, sales, or customer engagement. Using the severity field allows us to communicate with developers and clients effectively. It reveals how dangerous the defect is for the system and how quickly it should be fixed.

A brief overview of basic severity levels:

  • S1 — Blockers: The functionality is not working or is blocked in its critical path.
  • S2 — Critical: The issue is blocking some functionality. However, there is an alternative way to use it and finish the path.
  • S3 — Major: The Feature/component/functionality is working; however, not according to the documentation or does not meet all the acceptance criteria
  • S4 — Minor: The issue does not have an impact on the functionality but rather is related to the UI aspect
  • S5 — Trivial: A defect has almost no impact on the functionality overall or the performance of the software. It can be a typo or a wrong copy.

8. Preconditions

This step is optional. It’s a set of information for the developer on what needs to be done before executing the repro steps to recreate the issue. Remember to make it precise and clear.

9. Reproduction rate

If you cannot reproduce the bug, the developer will not fix it. We need more than memorizing and including the steps in our ticket. We need to make sure the issue occurs every time after following the steps. In such a scenario, it is essential to check how often per x uses the case to report a bug.

10. Steps to reproduce

A common way, and our best practice, is to write the repro steps as a numbered list / a sequence of actions that lead to reproducing the issue.

For example,

  1. Open Home Page
  2. Click the “Menu” button on the left top corner
  3. Hard refresh the page while the menu is opened
  4. ….etc.

11. Actual results

If you master the skill of writing decent bug titles, this part of the bug report will no longer be valuable for you or the developer. To make it short:

Perfect bug title == your actual result.

If your bug report is on point, you will no longer have to duplicate already provided information.

12. Expected results

In this part of the report, we need to write an expected outcome for the path described in the repro steps section.

  • What is the expected behavior of the functionality under these circumstances?

Of course, the expected results cannot be just assumptions. You need to base them on technical and project documentation.

13. Attachments

At the end of each bug report, you should always upload additional documentation of the defect occurrence like

  • Screenshots
  • Screen Recording
  • URL links to documentation
  • Etc.

It will prevent misunderstanding the problem and provide an overview of the defect itself for the DEV team.

Just remember:

  • The attachment should be relevant and clear
  • No additional music from Spotify
  • No random memes/notifications in the background
  • No sensitive data is visible (for example, from another project).

Wrapping up

The rules for creating concise, factual, and understandable reports apply to all team members. Making the documentation that other team members understand can easily save you and others’ time and budget. On top, a good report can increase the team’s efficiency and improve communication.

Now that we revealed all the good practices from Airnauts QA Vault, it’s time to turn the theory into practice and apply it in your work. We hope that now you will know how to create a bug report that developers will love! So save this bug report template and make good use of it!

--

--

Airnauts

Enabling forward thinkers to turn great ideas into greater results through technology & creativity.