How to report bugs?

Posted on October 17, 2016 by Adrian Wyssmann ‐ 7 min read

When I used to work as test manager I encouraged my people to write issues/bugs that have certain quality. But actually this is not only true for testers but generally for everyone who reports bugs - especially if you are not in direct contact with the developers.

But even so if you have direct contact with the developers or you are a developer yourself, if you cannot immediately fix an issue, it is essential that you note it down and whenever you look into it later (tomorrow, in one week, in one year!) you should be able to understand the bug.

Preparation steps

Before you create a bug report you should consider some points

1. Check for existing Issue(s)

For the one managing the bug reports it is simply annoying if he get the same bug reported over an over again only to the reject it as duplicate. Therefore …

  • Check if the bug already exists in the existing bug tracking tool. Try to search different variations and combinations of terms

    Remark: Search works only as good as our bug title and bug description. Thefore see below on how to report bugs

  • If you think that there should/could be an existing bug but you can’t find it, please get help from the others (testers, developers, …)

  • Check your bug reporting process and see how you can add missing or additional information to existing bugs

2. Look at the details

Always check the details of the error message or application exception. At a first glance the error message you receive is the same as already reported, but when checking the details it may show that it’s a completely different error (different line of code, different class, ….).

Detailed error message shall be part of the bug description and not as an attachment - so this information is searchable. Only link existing bugs to test cases if they match the one you are facing. Otherwise create new bug reports.

If you don’t understand an error message, ask for help. Talk to developers first, but also talk to other testers or any other person which may help you to understand the error message.

3. Check for Reproducibility

It is very helpful if an issue can be reproduced, so aim for it and take your time to check different things and see whether the bug us reproducible …

  • … under the same conditions again (same environment, same version)?
  • … in different environments?
  • … under different configurations?
  • … with other versions of the SUT (to ensure that the bug was created or umasked now, because of an actual change)

I experienced that when the issue is not reproducible one may not been able to fix the root cause but only implement a preventive action. For testing on the other hand, means that they will not be able to show with their testing, that the bug is fixed but may only verify that the preventive action implemented does not cause side effects.

Bug Report Creation

If the preparation is done, then the bug can be reported. A bug report usually consists of several elements.


The summary of an issue shall help anyone who reads it to get an idea about the issue therefore consider this rules for a title:

  • short and succinct and unique title
  • high level description for easy reference
  • only includes the most relevant details, that differentiate the issue from others - keep the details for the description

Remark: In the environment I used to work, the summary of a bug was often show in documents (e.g. Release Notes) which are also relevant for a submission to a regulatory instance. Therefore choose your words carefully and avoid terms which could lead to confusion imply a critical error if it’s not. An example is the terminology “Delay (of resulsts)” for a medical device. Delay of patient results is critical but in case it is not really a delay of results you may use other words like “performance issue” or something similar. I think you get the idea. It may be good practice as well to define a common glossary or alternative phrases for your team.


The description shall be a very detailed description of the issue. Remember that this information is searchable and therefore shall contain all relevant information and keywords. I recommend to have following aspects covered in the bug description

Problem Description

The first line describes the problem in more details that the summary

  • Highlight the most important information first!
  • Do not only repeat the summary/headline of the bug
  • Describe the problem and document the difference between expected and actual results
  • Write the bug normally including Screens (DB, GUI etc.), Logfiles, Video or DB. Do not attach something only, when it is 100% clear what’s the issue & reproduction steps & root cause(s) are.

Bugs must be generalized i.e. a single example of a failure is not enough. The bug reporter must expand the investigation, asking themselves questions and include the answers to those questions. They are useful hints for the people who will process the bug. For example …

  • Are there other areas where this bug could occur?
  • Are there areas where it doesn’t occur?
  • Are there areas which I think could be affected but I cannot check?
  • Is this bug specific to a test environment?
  • Did it affect older versions?

Reproduction Steps

Reproduction steps: the simplest, shortest, easiest possible!

At this point the bg reporter must reduce the bug to its simplest expression.

Remember that the developers who will reproduce the bug need to be able to do so as quickly and easily as possible (and they may not have access to devices, huge pre-populated db, your test environment, the test case which discovered the bug, …)

If you know of a test case that can be used to reproduce or retest the bug, mention it, but for information only (this information is later on helpful to track bug coverage or necessary test case updates)

Explain how what you witnessed compares to what you expected

Advocate the issue: What is (are) the worst consequence(s) this issue could have?


Document workaround(s) if exist(s), this can help other users facing the issue and - in an enterprise environment - the customer support can use it to help the customers!

Testers will be grateful to be able to easily work around the bug so they can carry on with the testing!

Environment and Configuration Information

Information on which environment you have discovered the bug (Server, Client) and under what configuration (SUT Configuration, Server Configuration, …). This can include if applicable:

  • Software version(s)
  • OS and Server Architecture (e.g. Windows 2003 SP1, 32-Bit)
  • Customer DB or new DB (e.g. empty DB)
  • Time Zone of client (e.g. UTC+1h)
  • Regional Settings (e.g. dd/MM/yyyy, HH:mm,,x)

Details to installed drivers/3rd party apps (if applicable)

Drivers and 3rd party apps/pluginy interfere with your system and thus may have have an influence or cause the issue. This information is also very useful if you want to retest an issue appropriately or especially on a customer system.

List of used devices (if applicable)

This may not be applicable for software only projects but in case you work with software that has devices attached provide a list of used devices incl. S/N and SW i.e. firmware version e.g. in case you have system tests in conjunction with connected devices.


I have often seen that simulating devices works fine but when finally testing with a real device the device (e.g. firmware) may behave differently than specified and therefore causing issues in your application.


As already mentioned, an attachment is not a replacement of a proper bug description (i.e. don’t document your bug in a Word document and us it as bug report). Information attached to a bug report shall provide additional information to debug and fix the bug. So …

  • Allways attach relevant logfiles (if you don’t know which, ask)
  • Attach test data files in order to reproduce a bug - if applicable
  • Add screenshot or video as an additional, illustrative purpose - make video if an issue is hardly to describe in order to get a full understanding of the issue (only show relevant information in the video).

Some words to filenames: In my opinion the file name should not be a description what’s shown on the image (in case for images) or written in the document (in case of txt or doc files) but rather a unique identifier which can be referenced. If the attachment needs further explications write this in the bug description or as comment where you attach your file (if available in your bug reporting tool).

What else?

Well with the information above you cover the most essential information. Depending on your environment and also your tool it may make sense or is even required to provide additional information. I recommend to provide some guidance for this information as well.