HomeBlogHow to Write an effective bug report?

How to Write an effective bug report?





A Software Bug can be described through the detailed explanation of the unexpected behavior happening as a result of some action performed on the software application. In bug reports, try to make very clear what are actual facts and what are speculations. Leave out speculations if you want to, but don’t leave out facts.

An effective bug report can save time for developers and testers and other stakeholders. Ideally, a ticket should stand alone, including all the information needed to reproduce the bug and it should be written in a way that even a non-technical person can understand and reproduce it.


First thing first: Try to produce the bug at least 3 times

Yes, 3 times at least? You ask why? Believe me, you don’t want to take 20 to 30 minutes of your time to create a bug report and then see it’s not there anymore! How could it possible? that’s easy, a part of a whole system (including hardware, software, and network) might fail that specific time and after it works again correctly; so what do you want to do? Begging the system for that bug back?!


Report one thing per case because minimalist is beautiful!

Never include more than one bug or failure in a case. This can make everyone confuse and it’s against clarity. Keep it minimal and simple and make everyone happy!!


It’s not personal, keep it professional:

Some bug reports look like friendly chats. They started with some phrases such as: “Joe, as we discussed before” or “As Jane notified us that day”. You, yourself will not remember what discussion or which meeting you were mentioned there, so you cannot expect the others sometime at future can understand that. If you need to mention such conversation, bring a brief summary of that to save everyone from confusion.


Bug Report Standards

Here I bring some principles and suggestions to write a standard and effective bug report. You may agree or disagree with me on this; I shall be grateful if I have your comments here (find it at the end of article).



The title should indicate the main problem and includes basic information about the place it points. It needs to be highly readable and easily referable. If you will use acronyms on the case description, use complete words on the title and add the short in parenthesis.

Since the case title could always be viewed inside of other cases, I suggest adding the related case number at the end of title as a reference.

Example: Wrong Credit Card (CC) number is accepted by payment system (ref. #2034)



The summary should stand alone to let the reader understand and identify the issue quickly. The goal of the summary is to make the report searchable and uniquely identifiable. Bug summary does not include technical details and it is just bringing a brief explanation on this in one paragraph.

In short, bug summary should be written in a way that even the grandma next door can understand it!

Example: In our payment system where the users are asked for their Credit Card number, the system will accept whatever numbers they put and so it will be considered as successful payment where it is not.



In a good bug description, you describe the issue precisely and completely in both general and technical words, statements and expressions. You may include all the necessary and relative information.

Please note: Only relevant information should be included and if in case you need to bring other relative cases for this case, indicate case numbers as a reference and where the information is located. If the bug only appears after a certain sequence of events, then at the next step you will bring those list of events.

Also, you can bring some references in your description if you think they are necessary to read by stakeholders.


Example: Bank Identification Numbers (BINs), which are the first six-digits of the account number, are fundamental to payments. They identify the issuing institution for the account and ensure that each transaction is routed correctly. (1)

On July 2017, MasterCard announced that they will have a new (Series 2) the initial number of their new clients. Previously this company used Series 5.

Currently, our system is using Luhn algorithm to validate the identification of CC numbers. (2)

We need to change our code in a way that our system accepts new card numbers by MC.


  • https://www.mastercard.us/en-us/issuers/get-support/2-series-bin-expansion.html
  • https://en.wikipedia.org/wiki/Luhn_algorithm


Steps to Reproduce (Optional)

Here you indicate the complete and precise steps those lead to the error or defect.


  1. Open the URL: http://ourwebsite.com
  2. Click on product menu and then choose on product to buy
  3. Click on “Proceed to checkout”
  4. Select pay by Credit Card
  5. Fill out the payment form
  6. Click continue


Scope: (optional)

A bug may affect only one part or more than that in a system. You may indicate the scope of error and all of the areas

Example: All payment methods in checkout page except “Wire Transfer”


Actual Result and Expected result:

You are reporting a bug because you found something in the system that is deferred in compare of your expectation. For a better and faster feedback from developers or other stakeholders always indicate the current (actual) status and the expected status or values

Example: In the shop report page where there is our monthly revenue report, the final number is wrong. It shows summation of all sales but our developers forgot to subtract refunds. For example, our revenue on March 2017 was 12000$ but we had 1000$ of refund so it should be 11000$


Possible cause(s) of error (Optional)

If you can guess for what reasons and causes the bug is raised, you can suggest them here.

Example: the current Credit Card identification algorithm is out of date and needs to be updated


Suggestion(s) (Optional)

You can bring any suggestion or solution those could be useful for developers on the table but remember they can ignore them. Sometimes they will even ignore entire bug report by just saying it’s not a bug it’s a feature, a new unexpected feature of course!!

Example: this link could be useful to fix this case: www.braintreepayments.com/blog/supporting-new-mastercard-2-series-bins/

It’s not a bug it’s a feature!


Issue Tags or Labels (Optional)

Most issue trackers (Such as Jira, Bugzilla, FogBugz, etc.) have at least one way of grouping issues. Try to use meaningful tags, labels or categories to categorize your cases.

Some sample of good tags is performance, accessibility, usability, UI, admin, horizon, payment, shared server. Do not use tags that won’t indicate cases precisely, such as bug, defect, regression


Priority and Severity (Optional)

You can indicate what would be the bug’s priority to be noticed. The options are High, Medium or Low. Also, You can indicate how important and sever is the reported bug.


Screenshot (Optional)

A picture is worth a thousand words, but only if it has words to go with it! Most Bug reports should (almost) have a screenshot, but they should (almost) have descriptive text or signs on them.

On the screenshot try to use “Arrow”, “Label”, “Shapes”, etc to clarify your idea and points those a reader should notice to.

There are many commercial and free software available for this aim. I personally prefer “Snagit” software that has every feature you need to capture and modify the screenshots.

It is suggested to use Green color for the correct area(s) and Red color to shows error/should fix area(s). Also, try to save and attach the PNG format since it comes with high quality by default with good compression ratio.

@via: http://ronwhitman.com/it-doesnt-work-and-the-art-of-bug-reports


Bug tracking systems:

A bug tracking system or defect tracking system is a software application that keeps track of reported software bugs in software development projects. It may be regarded as a type of issue tracking system.

Many bug tracking systems, such as those used by most open source software projects, allow end-users to enter bug reports directly. Other systems are used only internally in a company or organization doing software development. Typically bug tracking systems are integrated with other software project management applications.

Some of well-known and popular bug tracking systems are JIRA, Fogbugz, Bugzilla, Apache Allura and Fossil.



Good bug reports can save significant amounts of time and money. It is always recommended to define a bug reporting process with some standards and format in your team whether you have a formal QA or not. Don’t risk your time and reputation by just create short and inefficient non-formal bug reports. Investing in a good bug reporting process will increase productivity and developer happiness. Choosing and using one of the mentioned bug tracking systems based on your need can definitely improve quality of your final product.



How to properly create a bug report







Please enter your comment!
Please enter your name here

Mehdi Shokoohi

Software Quality Engineer

Recent posts

Recent comments