The importance of writing detailed bug reports

This post originally appeared on Tellurium's "TestTalk" blog on 19 August 2014.

As software testers, we spend a large portion of our time (hopefully) pushing applications to the limits and using them in both expected and unexpected ways. This is of course all in the hopes of revealing underlying issues so they can be fixed before the software makes it to the end user.

Thus, whether we do manual testing, automated testing, or both, one of our most critical job functions is taking the problems we discover and documenting them in bug reports so they can be resolved.

Many new testers (myself included) nevertheless begin testing without an understanding of just how important it is that bug reports be accurate, specific, and clear, or what elements should be included to accomplish that task.

Read on to learn more about why detailed bug reports are so important and what you can do to make yours even better.

In the beginning

When I first started testing, I had no experience or knowledge about the testing profession at all (risky move on the part of our company, eh?).

Therefore, my testing mainly entailed manually using our application exactly as intended and making sure that the outcome was what I expected. I didn’t try to break things, or confuse our application, or take an unconventional path or workflow.

But the worst part? My initial bug reports.

To be honest, they stunk.

Looking through the first few issues I tested in our team’s bug tracker, I'm embarrassed by my testing and failure notes. I didn’t offer any details about the conditions I was testing under or the steps I went through. There are no screenshots attached to show what I was seeing. And I was extremely vague – as in “it didn’t look right.”

Ughhhhh what was I thinking???

I wasn’t trying to be unhelpful; I just didn’t know what information I needed to include.

What I've learned

Unsurprisingly, my initial “bug reports” didn’t go over well.

I quickly learned that the level of detail and care we testers take when writing our bug reports has a significant impact on how difficult or easy follow-up work on the issue is for developers, for other testers, and even for us.

Good bug reports are important:

For the devs

• So they know what they need to do to reproduce the problem
• So they know what they need to do to fix it

For other testers

• So they can get ideas of things to try to trigger problems in the future
• So that if someone else picks up issues you’ve tested, they know what was done to test them initially

For us

• So if a dev or another tester needs to have more information about a bug, we can give it to them
• So when it comes time to test the fix, we know what was triggering the problem before and can be sure to try doing that

And that, my friends, is why just writing "I tried to use this feature. It didn't work." in a bug report won't cut it.

4 Elements of stellar bug reports

So just what should you do to make sure you’re providing developers (and other testers) with the best, most useful bug reports possible?

Be sure that your bug reports include these 4 elements:

1. A summary of the conditions under which you tested. If you're testing a web app, which browser(s) were you using? Which test user account(s)?

2. A clear breakdown (maybe a numbered or bulleted list) of exactly what you did, in what order, what the outcome of each step was, and whether that outcome was expected or not. If there are multiple ways to do something – like running a search, for example – which way did you do it? If you were choosing options from menus or typing values into fields, what values did you use? If automated testing revealed the bug, which test was it? Which result?

3. An indication of whether or not you were able to reproduce the issue. How many times did you try? Did the problem happen every time, or only occasionally?

4. Any screenshots or videos that may help illustrate the problem further.

Now, including all of this information in your bug reports will make them longer. That’s OK. It’s better to err on the side of providing too much detail than not enough. Just be sure to organize the bug report so that it's easy for everyone to read and find what they're looking for.

If you really want to be sure you're on the right track, as developers or other testers for feedback on your formatting and content. They may offer valuable insight that will allow you to take your bug reports to the next level of awesomeness.

Now it's your turn

When you learn to think and test outside the box, you find a lot more creativity and fun in testing. But with that creativity comes great responsibility. Detailed bug reports are important for all testing, but especially things you do that are unconventional or unexpected.

Do yourself, other testers, and developers a favor and take thorough notes while testing so you can pass them on in your bug reports. Trust me: everyone will appreciate it.

What are some of your tips for writing useful bug reports?

For more testing updates, follow Cullyn and Tellurium on Twitter!