Search This Blog

Loading...

Thursday, July 17, 2008

Tips to Write a Good Bug Report

Writing is easy, but writing clearly is hard. When it comes to write bug report... well, writing seems to get even harder, as far as the IT professional is concerned. In my life as a developer I have seen a lot of bug reports that are either incomplete, or missing critical reproducible steps, or have no explanation of why the results are wrong. Imagine if you were a developer and you got this kind of bug report,  won't you feel frustrated? The best you could do is to mark the case as not reproducible and assigned it back to the tester. The tester, would, in turn would, insisted that the bug was there and, well, there went a football-kicking session. Congratulations, you've wasted a few non-productive minutes on just trying to get message across. All these wasted minutes would add up, resulting in a loss in productivity.
There are a lot of resources on the Internet that teach us on how to write a good bug report. I am sure some of the tips here are also available elsewhere. But even though the points are the same, but the presentations differ. So my hope is that for those who haven't know how to write a proper bug report, they can gain something after reading this post. As for those who are already knowledgeable, they would still find the  information here useful, or at least entertaining.
The Dos:
  1. Clear title-- Good title is a must, as the developer should be able to grasp the essence of the bug report from the title alone. If you have a large database, having a clear title will help the system admin to assign bug reports to the correct developers without even reading the whole reports.
  2. One bug per report-- Report one bug in a single report, no more, no less. If you put in too many bugs, some of the them may be overlooked. To avoid confusion and duplication, please, one bug per report, no more, no less.
  3. Minimum, quantifiable steps to reproduce the problem-- This is important. Developers need to be able to get to the problem in the shortest time. So the testers' job is to help them to do just that. Testers need to do a few round of testing to clarify the steps, and to be able to reproduce the problems using minimum steps. We the developers will appreciate the extra efforts, really. If the testers can't specify the steps to reproduce the problem, then the developers have to conclude that the bug doesn't exist.
  4. Expected and observed results-- A bug report should always contain the expected and observed results. A generic description like "This is a bug" is not helpful, because the bug in question is not immediately obvious to the developers. Another reason for spelling out explicitly the expected and observed results is that sometimes the developers don't think that the bug is a real bug. So it is the testers 'duty to explain to the developers what went wrong.
  5. The build that the problem occurs-- Daily builds are common nowadays. So if the testers don't specify the exact problematic build, developers might have a hard time trying to solve an already-solved problem. That will be a waste of resources.
  6. Include background references, if possible-- If a bug is related to other bugs, then please include those information in the bug reports. This will help the everyone who reads the report understand the issues at hand better.
  7. Pictures-- A picture is worth a thousand words! Sometimes words just don't flow; in that case why don't just capture a clear picture that illustrates the problem?
  8. Proofread the bug report!-- This is very, very important. Now the bug report is readied, but why not just trial run what is written to make sure other people can follow and reproduce the problem exactly? A proofread bug report has a much higher chance of being understood properly by the developers and fixed by them.
The Dont's:
  1. Don't write generic titles-- Don't write titles like "Help!", "What happen?". This kind of titles are devoid of content at best and irritating at worst. So please provide a clear, concise title to your reports.
  2. Don't use personal communications-- Put everything your know, all the latest developments in the bug report. Don't resolve the bug privately with the developers. The whole purpose of bug report is to capture all the interaction that is going on so that the knowledge won't be lost. Using personal communication, or resolve the cases privately is defeating very purpose of bug tracking.
  3. Don't assume that the developers can read your mind-- The developers don't have telepathic ability. Don't ask them "do you get what I mean?", or "you get me?", follow up by a confusing stare. Try your best to express yourselves, use pictures if possible. And don't assume, the developers can only follow things that are written on the bug report, don't assume them that they will do a few sextra teps you think are obvious.
  4. Don't kick the bug report around! -- We have enough politics in the office already. Using bug report to score political points is detrimental to everyone.
  5. Don't be rude-- Well, if you can help it :)
That's all from me, anymore?

9 comments:

Mathias said...

On the point of clear titles, a rule of thumb of mine is that I should be able to find my bug by the title alone, in a list of 100 bugs...
As for out-of-system communications, I partly disagree. Often, a 1-minute conversation will do wonders to clarify a bug, so direct communication shouldn't be discouraged either. On top of that, you don't want your team to be isolated in a bunker - feedback is good. The tricky part is to maintain a balance between these 2 aspects, because all information on the case should be documented in the system. Personally, what I like is to take requests only through the system, so that the initial effort is on the requester, but after that a discussion is fine, provided it gets documented in the system

Anthony Stevens said...

Great article. I am especially grateful when QA follows the "one bug per report" recommendation.

@mathias: I have to disagree with you and agree with the author on the introduction of out-of-system communications. Unlike much of software development, QA resources should be fungible and a new QA person should be able to get up to speed on the project right away using only the bug-tracking system and the spec(s) for the product in question. You can't do that unless you have everything documented in the bug tracker.

Rob said...

While I fully understand the problems with not capturing all the information, I have to go with Mathias on the direct communications issue, provided you pay attention to his last line: "provided it gets documented in the system".

After discussing with the tester/customer, getting them to take you through the system, asking them "what happens if you do this instead?" or whatever is quicker by phone/IM/in-person, you do need to make sure you capture the essence of the discussion on the report.

Akinom said...

Hello!
I am a tester. I fully agree to the author's ideas. They are correct. Whatever he says it is helping the developer, it is equally helpful to the tester when they need to re-test. Trust me. When you have 100 to 200 items to test, it's good to have a 'reminder' of how on earth one got there...
But sometimes, just as it happens to the tester not have the flow of words running, sometimes developers don't spend the due time reading the full report. Especially when you are using a bug tracking solution, and the information is tabbed, etc. So, yes, sometimes direct communication is good.

Santhosh Tuppad said...

Here is a crash course on bug reporting for testers who can better their bug reporting skills. If you are doing better already then you can share this with your colleagues or friends who are testers and newbies in software testing.

http://tuppad.com/blog/wp-content/uploads/2010/08/Crash-course-on-Reporting-Bugs-in-Software-Testing.pdf

-- Santhosh Tuppad

gregi said...

Thanks for this great article.

For web development projects it's really necessary to have a proper screenshot attached - as many of the tested bugs only occur in rare situations or in specific browsers like IE.

Providing such a proven evidence (Screenshot, exact browser version, ...) is sometimes hard for testers. Usersnap is a small tool which allows your testers to improve the communication to the devs by getting screenshots and important meta information attached to the bug report.

gregi said...

Thanks for this great article.

For web development projects it's really necessary to have a proper screenshot attached - as many of the tested bugs only occur in rare situations or in specific browsers like IE.

Providing such a proven evidence (Screenshot, exact browser version, ...) is sometimes hard for testers. Usersnap is a small tool which allows your testers to improve the communication to the devs by getting screenshots and important meta information attached to the bug report.

Jennifer Frank said...

Thank you for pointing out the correct way to write a Bug Report. It helps to know this kind of stuff if ever I'll be hiring a website designers phoenix. At least now I can assess if they really know what they're doing and if they can solve any future concerns that I'll have on my website.

pavan kumar said...

Hi,

Very Very good and usable post. Thank's to share your experience with us. I will try to remember these tips in my blog commenting task.

Project Managment Tool
Issues Reporting Tool