Guide to writing a Bug Report

Introduction
This document is intended to explain the steps needed to write a good bug report and explain
the main fields that the report should have.

What is a BUG
Before understanding what a bug is, we first must define quality. We will use Jerry Weinberg’s
definition “Quality is value to some person (that matters)”.

A bug is anything that causes an unnecessary or unreasonable reduction of the quality of the
software product.

Different companies have different names to describe a defect. Frequently, these are called
incidents, issues, PRs (problem reports), errors, faults, failures and others. We will use the
term bug throughout this document.

Why the bug report is so important

Bug reports are among the most important deliverables to come out of a test. These are as
important as the test plan and will have more impact on the quality of the product than most
other testing deliverables.

Effective bug reports will:

- Motivate stakeholders to wanting to fix the bug.
- Have all the information stakeholders need to decide whether to fix it or not.
- Improve the tester’s credibility.
- Enhance teamwork between testing and development

Following a few simple rules can smooth the way for a much more productive environment.
The objective is not writing the perfect defect report, but rather to write an effective bug
report that conveys the proper message, gets the job done, and simplifies the process for
everyone.

The bug report is also used for tracking purposes, and allows gathering information that
will help to measure the quality of the product.
What to do after finding a bug, and before writing a bug
report.
Our bug reports are a reflection of us and our knowledge of the product. We put our
credibility on the line with each bug report, so we must do it rightly. We will use Cem Kaner’s
approach to the steps to be taken before submitting a bug. This approach consists of 6 factors
(RIMGEA).

• Replicate
o Try to reproduce the failure you just found in the same environment as well
as a different one (if possible).
• Isolate
o Make sure to submit one report per bug. Identify the critical conditions and
the minimum set of steps needed to replicate the failure.
• Maximize
o Make sure the failure you are seeing is not only a symptom of a bigger and
more critical one. Do follow-up tests such as varying your behavior, varying
the options and settings of the program, varying the data that is loaded, or
varying software or hardware when needed.
• Generalize
o Show that the failure doesn't just occur for extreme conditions (i.e. corner
cases). Bugs reports that describe corner cases are much more likely to be
rejected or deferred. But if you uncorner the corner case and show that the
failure occurs under normal conditions for the average user it adds more
weight to the bug report meaning it is far more likely to be fixed.
• Externalize
o Put the bug in perspective. Understand it and describe the impact of this bug
to stakeholders who will be affected by it. You are trying to sell the bug so that
it gets fixed. Find relevant information from support cases, marketing claims
or even competitor products to put your bug in perspective when needed.
• And say it clearly and dispassionately
o To better explain this part, please read the “How to write a defect report”
section.

How to write a bug report

The report needs to be clear; having all the required information, if the report is well
written, other testers, managers and developers will easily understand it.
Consider the following tips to write a good defect report.

1. Condense - Say it clearly but briefly, this is applicable for all the defect’s fields
especially the title (read the Examples and Annex1)
2. Accurate - Is it a defect or could it be a user error, misunderstanding, etc?
3. Neutralize - Just the facts. No zingers. No humor. No emotion.
4. Precise - Explicitly, what is the problem?
5. Isolate - What has been done to isolate the problem?
6. Generalize - What has been done to understand how general the problem is?
7. Re-create - What are the essentials in triggering/re-creating this problem?
(environment, steps, conditions)
8. Impact - What is the impact to the customer? What is the impact to be tested? Sell the
defect.
9. Debug - What does development need to do, to make it easier to debug? (traces,
dumps, logs, immediate access, etc.)
10. Evidence - What documentation will prove the existence of the error?
Evidence may take the form of documentation from user guides, specifications,
requirements, and designs. It may be past comments from customer de-facto
standards from competing products, or results from previous versions of the product.

** This is based on ‘Writing Effective Defect Reports’ by Kelly Whitmill

Main fields for a bug report

Title
Definition
This field is crucial in a defect; it needs to be clear enough to give an idea what the
defect is without going into the detail of the steps.

Best Practices
• Should describe the problem in a simple manner.
• Should be clear and understandable for anybody.
• Should not be long. The recommendation is that these are not more than 80
characters.
• Use acronyms, tags that were defined in the project, for example some
projects use MMC as an acronym for the Microsoft Management Console
Framework
• Use of key words (e.g unhandled exception, hang, typo, etcetera )
Description
Definition
It needs to contain all the details of the defect in a summarized way.

Best Practices
• The description needs to explain the defect in an accurate and precise way.
• If the defect contains attachments it is very helpful to mention this in this field

Requirements/Environments
Definition:

It contains the hardware and/or software information where the defect was
observed.

Also, it can contain the configuration details that are relevant for the product, for
example: types of identifiers like user accounts, passwords and privileges

Best Practices
• If the defect is reproduced only on a specific environment the details of the
environment needs to be included in the requirements/environments field
OS versions and service Packs.
SQL versions
How components are installed
Browsers
Etcetera

Reproduction Steps
Definition:
The Steps needed in order to reproduce the defect

Best Practices:
• Steps must be written as a command sentence (For instance, ‘Click Ok’)
• The steps need to be detailed enough so someone who is not familiarized with
the application can reproduce the defect easily
• Enumerate the steps sequentially
• You can add sub steps or notes for each step
• The number of steps needs to be short
• Use special characters, or styles to highlight names and options
• Attachments that can help reproduce the defect can be mentioned in the steps,
for example when a step mentions that it is needed to create many users

Actual Results:
Definition:

This field is used to specify the actual/current results that will describe the
unexpected behavior from the execution of the steps.

Best Practices:
• The description of the actual result must be clear and punctual. Cannot be
vague.
• If a screenshot with the actual results was attached it can be mentioned here.
Expected Results:
Definition:

This field is used to specify the expected results of the functionality that is being
tested.

Best Practices:

• If possible, point to a requirement document or other to support why you

expect this result
• It should not be ambiguous. Avoid using sentences like this “it should work
properly”

• Have an example, if applicable

• If the tester is not sure about the expected results, he needs to co-ordinate
with his team

Severity
Definition
Severity indicates the impact of the defect on the application that is under test, among
these you have:

1. Critical - Application will not function or system fails

2. Major – Part of the application will not function
3. Medium - Severe problems but possible to work around
4. Minor – Does not impact the functionality or usability of the process but
is not according to requirements/design specifications

0. Critical - Application will not function or system fails

1. Major – Part of the application will not function
2. Medium - Severe problems but possible to work around
3. Minor – Does not impact the functionality or usability of the process but is
not according to requirements/design specifications

Note: The severities can be different for different companies

Attachments
Definition
 This is used to attach files that help the developer to identify the root cause of the
defect for example log files, demos, screenshots and etc. This helps to understand the
defect faster when there are many steps that need to be executed to reproduce the
defect.

A dditional fields for a defect report

There are other components that can be used in the report.

Version
Definition
This field is used to specify the product version where the issue is found.

Target Release
Definition:

This field is used to define in which release the defect should be fixed

Best Practices:

• The default value should most often be the current release version; otherwise
asking the team is always a way to make sure you are on the same page with
them

Workaround
Definition:
This field is used to specify the workaround. A workaround can be considered as
temporary fix that allows the functionality to work. And, this doesn’t mean that the
defect is fixed, that is something development must do

Best practices
• The workaround needs to be clear and punctual in order to provide a good
description and clear steps
Legacy
Definition:
This field is used to specify if the defect is Pre-existent in previous version

Best Practice:
• If the tool does not provide this field then it is recommended to set this
information in the description field whenever it is possible

Bibliography
- ‘Writing Effective Defect Reports’ by Kelly Whitmill