tech · 10 Feb 2023

How to Write a Bug Report That Will Make Your Engineers Love You [+Bug Report Template]

Anna Serguts

Anna Serguts

QA Engineer

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, well-established communication between its members built around a strong team spirit. 

In this article, we will share our approach to writing bug reports 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, a 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 that perform bug fixes.

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 a 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 software, your template could differ. However, the following fields are required when reporting bugs in any system:

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

In addition to the required bug reporting 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 can 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.png
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


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 three simple questions 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 on what attributes/fields should be used and what gradation should be applied. 


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 can 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 items such as Environment, Steps to reproduce, Expected Result, Actual Result, and even Attachments.


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.png
Steps to reproduce. Source:

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 outcomes, 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.


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 to report bugs. So here are our recommendations for writing an 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!

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. 

About Orangesoft

Orangesoft is the leader in app testing and QA services. According to Techreviewer, Orangesoft is a top QA and software testing company. We provide a set of flexible, scalable, and on-demand testing services: regression testing, usability testing, localization testing, payments testing, and other testing services. Orangesoft clients include IKEA, Adidas, Hamleys, CoachNow,

What is a good bug report?

A well-written bug report is concise, clear, and to the point. It should include the minimum amount of text but deliver as much information as possible. Also, bugs in the report should be reproducible to be fixed.

What is a bug report in QA?

A bug report is a technical document that outlines exhaustive information about the bug, the environment, and the steps to reproduce it. This document is a crucial artifact for the development team as it allows developers to identify and fix an issue faster and make the software more reliable.

How do you write a bug report?

Bug report templates may differ based on the bug-tracking software. Usually, a bug report includes a description of the bug, the environment, and steps to reproduce. A QA engineer should also specify the expected and actual results of a specific action. Also, you can provide more detailed information about the project's nuances, the developers', and the product owner's preferences.

How do I create a bug report in Excel?

Each team has a unique and established way of writing a bug report. Therefore, we recommend using a bug report template approved by the team at the beginning of the QA process. If you struggle to find the right template, you can download our free bug report template that has all the necessary information at the ready.

Rate this article!

(54 ratings, average: 4.7 out of 5)