tech · 23 Jul 2020 ·Clock7 min

How to Write a Bug Report That Will Make Your Engineers Love You

Anna Serguts

Anna Serguts

QA Engineer

Hero
Illustration by Amir Kerr

The success of any project largely depends on the team’s skill set. A strong team has a mix of hard and soft skills and, more importantly, a well-established communication between its members built around a strong team spirit. 

In this article, we will dive into relationships between developers and testers, share our approach, and reveal our bug report template. Testers should deliver a bug description in a clear, structured format, making it easy for the developers to reproduce, understand, and fix the bug quickly. Communication and straightforward bug reports speed up project development.

What is a bug report?

According to Wikipedia, bug - is an error, flaw, or fault in a computer program or system that causes it to produce an incorrect or unexpected result or to behave in unintended ways. 

In other words, bugs are a real pain for every project. They could lead to various problems, such as delayed app release, failed marketing campaign, damaged reputation, or the project's very existence.

A bug report is a technical document that contains all the necessary information about the bug and the conditions under which it can be reproduced. It is a guide for the developers and the team engaged in fixing the bug.

Everyone can write a bug report, but is every bug report effective? Our QA team writes detailed bug reports, which allows the entire team to release projects successfully. Developers love our QA for that exact reason.

Check out the other testing documentation at Orangesoft in our article on the mobile app testing process.

What should a bug report look like?

There are two main criteria for a well-written bug report: 

  • Reproducibility. As soon as the developer has seen and reproduced the error, it can be fixed. Without reproducibility, bugs may remain unfixed.
  • Clarity and information value. The description must contain the minimum amount of text, but provide as much information as possible. An extensive "essay" can only confuse the developer.

Keep in mind that every bug report returned to the tester with the status "Can’t be reproduced" or "Information required" is a total waste of time for both the tester and the developer. That is why it's crucial to provide a high-quality and well-written bug report.

We recommend using a bug report template approved by the team at the beginning of the working process. You could create it using good old Excel tables, but we suggest using bug tracking systems. Our team uses Teamwork, but you can choose a platform that suits your taste and project, such as Jira, Trello, Mantis, and Redmine. You can find the full list of top bug tracking systems in the Capterra catalog.

What should the bug report contain?

Depending on the bug tracking system, your template could differ. However, the following fields are required:

  • Title
  • Severity/Priority
  • Description
  • Environment
  • Steps to reproduce
  • Expected result
  • Actual result
  • Attachments (screenshots, videos, text)

In addition to the required bug report fields, you could add more details depending on the project's nuances, the developers' and the Product Owner's preferences.

  • Unique report number (ID) 

Each bug report must have a unique identifier. It usually consists of the first letters of the project’s title and a serial number. Most bug tracking systems automatically assign an ID for each bug.

  • Author

Most bug tracking systems have this information by default, so you could quickly contact the tester who found and described the bug.

  • Assigned to

This section specifies the information about the developer who will fix the bug. Depending on the project's agreements and organization, the bug can be assigned to a senior QA or PM who will decide which developer should fix it.

  • The status that shows the current stage of working with the bug
Bug life cycle
  • Incident type

We believe it is essential that testers report not only Defects/Bugs but also the possible improvements that could be implemented on the project. 

  • Creation date

Required fields of the bug report in detail

Title

The first and most important attribute in any bug tracking system is a brief description of the problem, which allows you to quickly navigate the issue and describe it with simple “What? Where? When?"

For example:

What? - The photo doesn't load.

Where? - In the "Profile" section.

Under what conditions? - Tap on the "Upload from gallery" button.

Bug severity and priority

At first glance, these attributes seem to be the same, but they are not. Let's have a closer look. 

Bug severity

Severity describes the effect of the defect on the application's performance, for example:

  • Blocker. An error that causes the app to fail. 
  • Critical. A critical defect that causes some key functionality to fail. 
  • Major. A crucial error that indicates a deviation from business logic or disrupts the program, but doesn't have a vital impact on the app.
  • Minor. A minor defect that doesn't violate the application's functionality when tested, but influences the expected result. A design error would be one example.
  • Trivial. A bug that doesn't affect the functionality or operation of the app but can be detected visually, for example, a typo in the text.

Bug priority

Priority specifies the order in which the problem should be fixed. We use the following general gradation for this:

  • High. Anything that impacts the typical user flow or blocks app usage.
  • Medium. Anything that negatively affects the user experience.
  • Minor. All else (typos, missing icons, layout issues, etc.).

There are projects where bug reports contain only one attribute set by the tester. In our company, we generally use two of them. The tester usually sets only Severity, while the senior tester or manager arranges Priority depending on the project's primary goal or the Product Owner's preference. 

In any case, we recommend discussing and agreeing with the entire team what attributes/fields should be used, and what gradation should be applied. 

Description

This part elaborates on the Title field since quite often the table of contents becomes too cumbersome. This is where the description field comes in handy, so you could describe the problem without any restrictions. It also specifies additional conditions, such as how often the error occurs, if the error is accidental, and the circumstances that could cause it.

For example: 

“NOTE: the Account time zone = Atlantic time (Canada)”

In some bug tracking systems, such as Jira, this field also includes such items as Environment, Steps to reproduce, Expected Result, Actual Result, and even Attachments.

Environment

An application could have inconsistent behavior depending on the situation, so here you need to describe in detail all the conditions in which a bug is reproduced, for example:

  • Device manufacturer and model number
  • OS version
  • Application version
  • Network connectivity
  • Screen orientation
  • Browser

For example:

Device - iPhone XR.

OS version - 13.3.1.

Build version - 0.4

Connection to a Wi-Fi network

Steps to reproduce

This item should contain the minimum steps that describe the entire path of reproducing the bug. Describe one step per line. If the description requires more than 8 bullet points, you can mention them as Preconditions.

For example: 

Precondition: the user is registered in the system.

Go to the list of products offered.

Add product "A" to the cart.

Tap on Buy.

Steps to reproduce. Source: monkeyuser.com

Just keep in mind that obvious steps are not necessary. For example, you don't need to specify: "Open the app" and "Log in," unless the problem is directly related to these actions.

Expected result

Be sure to describe the expected result according to the technical task, design, test cases outcome, or the opinion of the tester. This way, the developer will know exactly what to focus on and won't waste their time searching for the necessary information.

For example:

Required fields are highlighted in red after clicking the" Submit" button.

Actual result

This field describes the actual effect of the bug. Sometimes testers  write general statements  such as "The Undo Button does not work properly." This is not very informative, is it? Does the button get pushed? Does the action not cancel? Or does another action not related to cancellation happen?

It's quite important to write a clear description of the actual result. In most cases, it coincides with the Title.

For example:

Required fields are highlighted in green after clicking the "Submit" button.

Attachments 

It is standard practice to attach files to bug reports because it's easier to perceive information when it is displayed visually.

For example:

- Screenshot (it's convenient when the bug is highlighted with a circle or an arrow), 

- Video (sometimes it could be difficult to describe the bug in words, so it's better to see it for yourself).

- Log-file.

Tips on writing a good bug report

You may wonder if something could still go wrong, even if you use the template. So here are our recommendations on writing the effective bug report:

  1. Don't be afraid to ask the Project Manager for help if something is unclear to you.
  2. Be sure to request feedback and suggestions from developers about your bug reports. Each project is unique, each developer is different, and it is crucial to find the right approach. A comfortable atmosphere and mutual understanding between the team members contribute to fast, high-quality work. 
  3. Re-read the bug report before saving it. You could even do that twice.
  4. Make sure that the bug report contains the description of only one error.
  5. Go over the error a few more times, correct the steps and add more details if necessary.
  6. Don't criticize or blame your colleagues. Mistakes are unavoidable, and they are not always easy to catch or fix. Remember, you are a team!

Read also: Your step-by-step mobile application testing process

We are sure that if you read and follow our recommendations above, the quality of your bug reports will increase, and the same goes for your development team's satisfaction. 

Rate this article!

(11 ratings, average: 5 out of 5)

red-title-line
Insights
Latest Articles
tech

10 Most Common Web Application Security Risks

29 Jul 2020time 11 min
client guides

Your Step-by-Step Mobile Application Testing Process

22 Jul 2020time 14 min