What should be included in a QA reported issue from a developer’s perspective

As a developer, handling reported software issues is one of my daily tasks. Those issues can be bugs, running environment issues, user mistakes and more. An accurate description of what actually happened is very important to a developer, otherwise there is no way to identify the issue. Sometime we can only guess based on certain assumptions, which is always not the case.

Issues are often reported by QA testers or end users. If your company have a QA team, which it should, issues reported by end users should be verified by QA tester before passed to developers for fixing. End users do not report issues directly to developers.

It is very important that QA testers gather sufficient information of any reported issues. Often I received very vague issue descriptions, like “App crashed”, “The feature is not working”, “Cannot take photos”, “Very slow”. With these descriptions I must be smarter than Sherlock Holmes to find out the root cause.

The problems with these information are:

1. It is insufficient to understand the actual issue encountered.
2. The provided information can be misleading.

Insufficient information

Users often give comments like “Very slow” without specifying which part is actually slow.

Do we need to test the whole application to find out which part is slow? Under what circumstances is the application slow? Do we have to do a complete stress test to find it out? If our system consist of client-side and server-side, do we need to test both?

As you can see, it is impossible to carry out such testing based on a simple “Very slow” comment from the user.

Misleading information

Users are not technical like developers. Developer communicates using various terminologies. A lot of terms have standard definitions which do not make sense to normal users.

For example on mobile devices there is something called notifications, which is a banner that shows up to user when received.

I once received a bug report stating that there is no “Popup” showing in app. The app do have “Popup” design in various screens, so I have been checking which part may have a “Popup” issue that causing it not to show. Turn out the “Popup” user mentioned is actually referring to app “Notification”.

Misleading information can indeed waste you a lot of time.

What should be included

So what should be included? Obviously we want to have accurate and detailed information. When issues reported by user, QA tester is responsible for gather sufficient information. After information gathering, she should start verifying the issue, if it can be reproduced then pass it to the developer, else ask the user for more information.

During this phase, QA tester triages and validates the reported issues, sometimes it could simply be a user mistake rather than software bugs.

“Microsoft programs are generally bug-free. If you visit the Microsoft hotline, you’ll literally have to wait weeks if not months until someone calls in with a bug in one of our programs. 99.99% of calls turn out to be user mistakes.” – Bill Gates on “Code Stability” from Focus Magazine

QA tester also need to transform user description to technical description to be read by developers. Like the above example, “Popup” need to be transformed to “Notification” in order to be understand by developers.

Now let’s list out the required items for a issue report.

1. Issue title

Simple enough, a brief title to describe what this issue is about. You can also include platform / environment in the title, for example:

UAT - App crashed when login with wrong password
Android - Wrong image is displayed when scrolling the contact list

2. Issue description

Brief description, no need to include the very detail of how it happens, it will be described later. For example:

Input username with wrong password in the login screen, then proceed login, app crashed immediately.

3. Steps to reproduce

This is the most important part of the report, it details every single steps to reproduce the issue, do not miss any steps even those actions might seem trivial.

For example:

1. Launch the app by clicking on app icon.
2. Click on the login button in the home screen.
3. Input correct username (testuser1).
4. Input incorrect password (123345).
5. Press the login button.

4. Test result

The test result, that is the actual issue observed.

For example:

App crashed immediately after pressing the login button.

5. Expected result

The expected result, the correct behaviour of the application.

For example:

App login successfully.

6. Test environment

This is very important information and most people do not provide any information on this. Some bugs only occur in certain environment, so make sure this part is not forgotten.

For example:

Android 13 Samsung Galaxy S23+, slient mode on, power saving mode on

7. Software version

With software version we can easily compare changes and sometimes bugs may have already beed fixed but not yet released. There are also chances that user is testing and old version of the software. You may also include the installation source of the software, user may be downloading the software from a wrong source.

For example:

3.0.32, installed from Google Play Store

That’s all

A good issue report can save a lot of time for various parties. I have personally been working at / with companies that have good issue reporting mechanism and it makes the issues solving process so smooth. It is always a good idea to invest in and enhance QA process to maintain software quality.

This article is written from a developer’s perspective, which describes what a developer wants and demanded.

There could be suggestions that are not practical from a QA tester’s point of view, maybe in terms of work efficiency, maybe the difficulty of gathering information from high privileged users.

This is understandable and hopefully I can at least point out the importance of how a issue should be reported, though the actual implementation is flexible.

Where to learn more

Guidelines and templates should be setup in the QA team for reporting issues. The best place to learn about this is GitHub.

Just browse the repositories of famous projects and read their issue reporting guidelines.

Look into their issues and see how people are filling in the details.