How to write a good bug report

Bug report is a technical document used to describe

Written by Phạm Đình Luật (PDL) from Safewhere team *

Bug report is a technical document used to describe an issue of the tested application failure found during test, helped stakeholders understand the problem, reproduce and resolve it. A good bug report will help us save a lot of time on figuring out the root cause as well as giving decision on fixing it. Good bug report is not only about its content but also about your pre-works before writing it. Following tips will help to write an effective bug report:

Ensure that the bug reports a totally new

Whenever you experiencing an issue during test, quickly find a shortest description for the issue and: Try to discuss with your closet team (usually QA team) to see ensure it is new but not spend much time on that Issue is never reported before Some time issue is new but according some technical limitations, we should consider it as limitation and ignore it. try to find on your bug tracking tool to ensure that the issue is new and valid If there is already bug logged, have a look to see if you can provide more valuable information, e.g. more step, more condition, the reproducible build number… Otherwise just ignore it, that will not only help time of write the bug report but also save time of other member in analyzing the issue. Reported a duplicated bug will waste not only your time but also the assigned person who will try to resolve it.

Ensure that the bug is reproducible

Or at least has a sequence of failure occurs for intermittent issue. Try to retest the flow that issue occurs and note down all steps as well as relevant information to provide to the bug report.

For intermittent bug, try to find how many times of executing a flow the issue will occur.

  • Report issue you see once in your life and unable to reproduce is very bad, it has no value at all.

Ensure that the bug reports issue with the tested application, not 3rd application issue

Ex: Sometimes sending email to external network is failed because of firewall/antivirus so it is not the problem failure. The issue should be ignored.

  • Sometimes failures is not yours so document it instead of raising a bug.

Ensure that all failure flows must be reported

When experience issue and it is reproducible, try to figure out to see if is there any other areas in the tested application having the issue. For example, in an application, user has phone number attribute and the design says that phone number must have exactly 10 digits.

  • When testing in web page, you can enter 11 digits => noted the web feature
  • The application also support editing user’s phone number via REST API => test the REST API to see it allows update value with 11 digits.

Write a clear, accurate and easy to understand description for the bug

Main sections of a bugs

  • Title: The title is the most important of a bug report:
    • Easy for someone to search the issue when reading the title.
    • Reviewer can make decision for the bug after reading the title instead reading the whole bug description / try to reproduce to figure out the root cause.
    • Careless develop will fix correct issue as sometimes they do not read the bug description carefully – that what we cannot prevent in real life.
  • What makes a good title:
    • Shortest description for the issue but contain almost information of the failure. Ex:
    • Title text is within a line, not more than 80 chars
    • Consider to apply convention to make reader easy to narrow down the issue. Ex: [Program_Product_Module_SubModule…]- short description
  • Product information: Provide information about application
    • application name
    • Hardware
    • Software
    • operating system
    • Browser
    • Tested version (build number)
    • Can be skipped if bug tracking tool provides fields for them.
  • Precondition: Provide some precondition steps before going to actually main flow, sometimes it is skipped as steps also mentioned in step to reproduce. Usually the precondition is picked from the relevant test case to save time of writing bug report.
  • Steps to reproduce
    • List down all steps in the failure flow that user has to go through to get the issue
    • The step must be detail enough to help assignee does exactly the same thing owner does e.g what action on control (left click, right click, double click, focus on…) or what data user enters.
    • Depending on the audiences, author can skip some “unnecessary steps” base on the level of the reader – it can make the whole bug look simpler but may risk for new member.
  • Expected result
    • Describe the expected outcome after the failure step, as detail as possible.
    • Point to requirement if any, this will help prevent unnecessary argument with developer.
  • Actually result: Describe what are facing after the failure step, following stuffs must be include
    • Screenshot of the failure
    • Error message
    • Log file/stack trace
    • Root cause guesstimate if any
  • Additional information: Can mention about the other area when the same issue occur which helps developer fixes the bug completed
  • Priority: The impact of the issue to customer, usually having 4 levels
    • 1 (Urgent): customer needs it fixed immediately
    • 2 (High): customer needs it fixed within a period of time.
    • 3 (Medium): customer needs it fixed but time depends schedule
    • 4 (Low): needs to be reviewed and made decision to fix or not.
    • Author need to assign correct priority so that the bug report will be fixed effectively base on time. Sometimes issue is reported from customer and the priority must be set according to requested fixed time.
  • Severity: The impact of the issue to system, usually having 4 levels
    • 1 (Blocking/Critical): impact to main functionality/features/data, no workaround.
    • 2 (High/Major): impact to main functionality/features/data, has workaround but difficult to do.
    • 3 (Medium/Minor): impact to minor functionality/features/data, has easy workaround.
    • 4 (Enhancement/Trivial): no impact, issue can be fix to make system works better. Usually UI enhancement / typo error.
    • The severity is very different base on the knowledge level of the author so it must be consider a review by experienced member in the team.

Benefit of writing a good bug report

  • Improve the communication between test team and upper management team: product manager, reviewer…
  • Save time as preventing duplicated bugs
  • Better relationship between test team and developer team as war/argument usually occurs between the two team because of bad bug report: unclear issue, missing steps to reproduce, unclear expected result, wrong priority/severity causing incorrect delivery time…
  • Fasten, effective bug fixing as less communication and waiting time, incomplete fixes