How to file a good bug report

How to file a good bug report

One of the first lessons, hard lessons, you learn coming into the world of software development out of college is how hard it can be to understand bug reports.

Variously they can be vague, misleading, inaccurate, confusing or best of all - misunderstanding a feature for a bug (the latter often points to usability issues).

Having endured many of these and now doing a fair bit of testing of my current application, I try to "be the change I wish to see in the world". So I've come up with the following scheme for bug reports.

#1 Start with a good short bug summary
For example:
"Data Entry screen disappears after entering certain unusual keystrokes"

The good part of this is a manager / team lead gets a quick idea of how serious this issue is (screen disappearing - bad!) where it occurs (data entry screen) and what caused it (unusual keystrokes). Useful in understanding just how serious it is and how soon it should be reviewed and/or fixed.

Next up you need to focus on the needs of the developer - basically instructions so the developer can reproduce the issue

#2 The *exact* build you are using
e.g.
March 27th 18:05 PM

Sometimes developers get dupe issues with related if not similar symptoms and having the exact build they can often realize "Hey that's that same issue I fixed yesterday" and they can then tell the tester - try the 28th build because it's related to issue X we resolved.

#3 Environmental Aspects
Including
- What machine the different parts of the system were running on e.g. web server, GUI etc.
- What database you were pointing at and DB login if appropriate
- How you installed the build e.g. options
- Your GUI login if appropriate
- If you can, it's really awesome to leave that build around and up-and-running so a developer can come over to your area and check it out for themselves. Not always possible but for those big critical issues it's a real time saver.

#4 Instructions to see the bug
The steps need to be detailed, step-by-step.

Often when I report a bug I spend a few minutes trying to get the least number of clear steps to reproduce an issue. This is important not only for the developer but for the person who subsequently tests the fix perhaps minutes, day or even months later.

You don't want to be too detailed "point your mouse to the 'Send' button and left-click" or too vague "enter some data and hit 'Send'"

1) Login to the GUI
2) Go to 'Tools > Data Entry > Advanced'
3) Select the 'Schedule' tab
4) Enter '03/04/08' and then without saving try to tab off
5) You get a System error (see attached)

5 Supporting Documentation
Screenshots are great 'proof' - especially for those developers you may know, who try to reproduce the issue for 5 seconds and then say "Unable to reproduce" and cancel your bug which you spent quite a bit of time entering. Very annoying!

Some folks who have long complicated steps often choose to add video capture too which is great (but bulky).

Logs are great too especially when they contain more useful errors related to things the developer can grasp e.g. Malformed SQL on line 223 of DataEntry.java.

Often these are attachments and as a technical lead I often trawl through the logs to find the most important lines e.g. often the first stack trace and then copy-and-paste that into the main bug description.

Other things you need in a bug report
- A unique identifier for this bug report
- Priority - Stick to High, Medium and Low - beyond that lies madness! :-)
- Severity is optional - often I find it confused with Priority for various reasons- again three levels should suffice - major, moderate and minor/cosmetic
- Who created the issue and when?
- Who is assigned the item?
- Who is the tester going to be?

Good bug reports take time. But it's worth it - I figure for every minute I put in to the report to make it clear and concise I'm probably saving 5 to 10 minutes of a developer's time and then more for the person who might have to test it (might be me 6 months from now).

As a team lead also I'll reject reports that lack these details. It's funny I've known some experienced QA folks who just can't seem to get this right - it's very frustrating to start a back and forth - which builds is this - please add logs - can you add a screenshot?- and then there are some who write them so well it just becomes a slam-dunk for the developer. Often they're the ones sitting right beside the developer - they've each learned how each other works - how to keep each other productive and keep frustrations to a minimum. That's good all around.