How to Write a Bug Report

Writing quality bug reports is a skill often overlooked by app development companies. But well-written bug reports can decrease the time between finding a bug and resolving it. Bugs can delay an app’s release, and problems with bugs can quickly spoil relationships with clients.

Today we’ll describe what a quality bug report should look like so you can avoid unnecessary delays in bug resolution and avoid strained client relations during your project development process.

Let’s compare a poor bug report with a good bug report

What does a poor bug report look like?

To understand how to write a quality bug report, let’s first look at how to write a poor one.

Imagine we’re working on a social networking website that connects football fans in group chats. After an update rolls out, a QA specialist fills out a bug report in JIRA. Let’s take a close look at this report:

At first glance, everything seems fine with this bug report, doesn’t it? We have a description, a summary, and some other details related to the issue. What’s lacking? Let's dive deeper.

Bug ID: JIRA gives an ID to the bug automatically, so we see nothing wrong here.

Bug Summary: This information is located below the ID. The summary of this bug isn’t specific. There are various types of users, and this summary doesn’t specify for which user(s) the bug occurs. A developer working on this issue will have to ask additional questions to clarify.

Bug Details: The tester didn't provide any data about the application version and testing environment. We will talk through these details further in the article. As for the priority, testers usually assign a priority level, which may change later.

Bug Description: This section raises the most questions. Here, the tester should explain Steps to Reproduce, Actual Results, and Expected Results. A bug report should give as much relevant information as possible. If your QA representatives don't describe how to reproduce a bug thoroughly enough, then developers will waste time trying to figure out what’s wrong.

After reading the description in our screenshot, web developers will immediately ask what login credentials were used: admin, test user, or moderator. Also, they’ll need to know the server (environment) on which the bug was produced. In other words, did this happen on a testing server, for example https://testing-bugs.sprinklebit.com, or a production server, for example https://sprinklebit.com.

The tester should also have provided Expected results. These details help a developer — who may not be very familiar with the app — understand the issue faster. Finally, we don’t see any visual documentation of this bug, such as attached images.

How do you turn a poor bug report into a quality bug report?

Let's now take a look at the next screenshot. This documentation is much better than the previous bug report.

What’s changed? The second bug report is much more specific. Web developers can work more efficiently when their documentation has all data they may require.

Let's explain what was improved in this second bug report.

The tester described important details in the summary: “Chat – the creator of a group conversation cannot rename it”. We also see other valuable information under the categories: Affects Version/s, Environment, and Fix Version.

The tester mentioned the version of the app in which the bug was detected. The environment is also specified, meaning the version of the website on which the bug was found. The tester further indicates in the bug description how the functionality must be implemented and shows how the bug was reproduced. The Steps to Reproduce discloses necessary login data, the address for the relevant version of the website, and a description of which buttons were clicked. The actual result is corroborated with a screenshot. Lastly, the tester didn't forget to mention the expected result.

We want to emphasize that any bug report should always be written in accordance with a set of rules. There aren't many of them, as the structure of a bug report is pretty much standard across all bug tracking programs.

Here are our further recommendations for how to create a high-quality bug report to make developers happier and more efficient. In the end, your application will benefit when bugs are correctly reported and resolved quickly.

High-quality bug report know-how

The aim of bug reporting is to explain an issue to web developers as soon as possible to aid overall project development. Before the QA services team starts writing a bug report, they should know the answers to the following questions:

• What? – What has happened with the application?
• How? – What did we click/do to produce the bug?
• Where? – Where exactly in the app did we find the bug? What is the webpage and/or server (environment)?

The next part of our article shows a good structure for a bug report.

Structure of a website bug report

Bug ID

Your testers may use a bug tracking system such as Bugzilla, JIRA, Lean Testing, or some other software that automatically assigns an ID to the document. Alternately, testers should assign an ID manually. Using an ID will save much time for developers compared to the alternative of writing out a full title.

In practice, almost no one manually writes bug IDs today. But if you do, you could use an application’s abbreviation. For example, we use SB-WEB for the web version of SprinkleBit, or SB-MOB for the mobile version. Also, testers should add an index number for the current bug.

Good: SB-WEB-121 or SB-MOB-231

Bad: My-Beautiful-Website-#87123 or simply #112

Developers may work with several projects concurrently, so a well-defined bug ID will immediately cue them in to which application and version a bug was reproduced in.

Bug Summary

In JIRA a summary is similar to a title. The summary may be considered the main part of the bug report. For starters, we advise testers to use short and informative titles. A bug summary usually consists of an Epic and short description of the problem. Epic in JIRA is the name of a large chunk of functionality, like Chat or User Profile. A short description is one or two sentences that tell exactly what happened. Ask your testers to avoid describing emotional reactions or subjective opinions.

Good: “About the company screen. Red strip on the top of the screen” or “Layout issues in the 'Rules' screen.”

Bad: “Something wrong with Rules” or “Why are there problems with the screen???”

Bug Details

As experienced QA engineers, we strongly recommend that your testers state the application version as well as the test environment. Usually, an application is updated every two to three weeks. For example, we might issue a new version of an app with bug fixes every two weeks. This means that there’s no need to create a late bug report about some problem in the 2.01 version if we have already implemented the 2.21 version by now. Ask your testers to add new reports in a timely manner, and always to specify the exact version of the application in which they reproduced a bug.

A test environment can be a website version, an operating system, or a web browser depending on the type of the bug. For instance, you may have two websites – www.my-website.com and testing.my-website.com. These are two different environments (test server and production server) and they may exhibit different bugs. Therefore, testers must indicate this data as a URL in their bug report. A browser name and version is usually mentioned if layout issues were found. Ask testers to always report an environment. It makes the work much easier as web developers will know exactly where testers discovered an issue.

If your testers don't add this data, then developers may check an irrelevant test environment. They won't find a bug there and may even close the task while the bug persists.

Bug Severity and Bug Priority

These two metrics may either be listed as separate characteristics or united in one parameter. It depends on the bug tracking system your testers use. Bug Severity is an estimation of the impact of the bug on the application, along a scale ranging from critical (a bug blocks key functionality) to low (a bug is very difficult to reproduce; main functionality works as it should, but there are minor issues with some rarely used functions). Generally, testers use this tool.

Bug Priority, in turn, is a tool for outlining the hierarchy of bug fixes. Project managers usually set a priority. Bug Priority is ranked along the same scale as bug severity, from critical to low.

In short, if key features don’t work, then a bug is ranked as ‘critical’ for both priority and severity. But when a non-working feature is rarely used, we assign a critical level of Severity (this bug concerns functionality) and low level of Priority. Below you will find a real-life example.

Example:

“Wrong spelling in the H1 heading 'Thes is our website!' on the landing page.”

This bug gets Low Severity because it doesn't influence functionality. Users are still able to do something on this page. But we should assign High Priority to this bug, because this is a heading – the first thing a user will see when coming to your website. And there shouldn't be any spelling mistakes.

In reality, our testers initially specify the Priority in JIRA. They should then inform web developers and project managers about a bug and its priority and/or severity. Then the project manager may contact the client and tell them what happened. The client then decides whether this issue must be resolved as soon as possible or if it can wait. The client's opinion may be different from what a tester thinks, so these priorities may easily be changed.

Bug Description

Testers should provide developers with Steps to Reproduce and Results in this part of the bug report.

Steps to Reproduce

This part of a bug report is dedicated to a description of how the bug occurs. The more informative testers are, the better. Steps to Produce include:

• The description of where in an application an action was taken. Testers should mention a browser, its version, and the system state: a user type, user state, system initial data, and the page where a user was.
• Actions – what a tester does to produce a bug.
• Actual results and Expected results.

An actual result is what happens when a tester reproduces a bug. Ask your QA team to provide a screenshot of the actual result for comparison with what was expected. An expected result is what we predicted as normal functionality under the given conditions.

In the next table, you will see a comparison of poorly-written Steps to Reproduce with well-written Steps to Reproduce.

Attachments to the bug report

This is the last section of the bug report. If necessary, a tester may attach any relevant additional documentation. The goal is to gather as much documentation as possible. Attachments generally include: screenshots, a log.txt file, or a file that a tester was trying to import.

We just described how QA engineers at RubyGarage organize and report bugs. Some details may vary depending on the bug tracking software, but following these guidelines should help you produce well-written bug reports.