How to write a good bug report

How to write a good bug report in 5 simple steps Tweet This

There is an expression, “Garbage in, Garbage out” and nowhere is this more true than in the writing of bug reports when you are testing a system.

Nothing is more frustrating than asking somebody to explain a problem they have encountered and getting a reply like, “It doesn’t work.”

Well, yes. The fact you are talking to me is evidence that something doesn’t work, but I can’t do a single thing about your problem unless you tell me something more specific like “When I am on page X, I can’t enter any text in the Y field.”

If you have to do it, do it well

This might seem like basic common sense, but, believe me, trying to get comprehensive and actionable bug reports, even sometimes from experienced developers, can be like pulling teeth. Nobody likes filling out forms, particularly when they are under deadline pressure and they know that every bug they document pushes that deadline further away.

But a good bug report doesn’t have to be that complicated and, once you get into the habit of doing them, they don’t take much time. Plus, when reports are done well, it’s much quicker and easier to understand and reproduce the error, fix, retest and then stabilize.

The simple 5 step system

Below is the 5 step system we use at Evo Pricing to write a good bug report:

  • Check if you are using the latest version

  • Isolate bug

  • Check if the bug is known

  • File each issue separately

  • Assign

The first step in writing a bug report is to identify exactly what the problem is; saying exactly what is wrong, and how to reproduce it. If you can tell exactly what is wrong, and reliably reproduce an example of the problem, you’ve isolated a bug.

Next, you have to check if you are using the latest version. Bug reports should be based on the latest nightly build. Then we can check to see whether or not the bug still exists.

The third step is to check if the bug is known. If it is not already documented in the issue tracker, “Create a new issue”.

It is important to file each issue separately to avoid confusion. If you have multiple issues, when you file them separately, they can be tracked more easily. Yes, it can seem like more hassle but, in the long-term it makes things easier all round.

Finally, assign the issue to the relevant member of the team.

Describing and reproducing a bug

In order to describe the bug you need to outline the steps to reproduce it.

First, a quick  overview of the thinking behind the steps you need to follow to reproduce the bug:

  • A good set of instructions includes a numbered list that details each button press, or menu selection.

  • A bug report requires clear instructions so that others can consistently reproduce it. Many bugs require some experimentation to find the exact steps that cause the problem you are trying to report.

And now, because I personally hate it when people give me an outline but don’t show the actual process in action, I’ve provided a basic example for you to use as a template.

Example bug description:

  1. Open Excel

  2. Login

  3. Click on Tasks button and open a task

  4. Click on Processes button

  5. Edit input sheet

  6. Click on Create

  7. Enter 10 and click on Save

  8. Select the new scenario and click on Get from processes panel

  9. Click on Update button and click on Send

Keep it simple

Note the simplicity of the language and the use of the imperative. Remember, we’re not looking for a novel, just a clear and simple outline of the steps we have to follow in order to reproduce the bug.

Then, once you have outlined these steps, describe expected behaviour vs. actual behaviour. 

Expected behaviour:
Describe what should happen if the bug was fixed.

Actual behaviour:
In contrast to the expected behaviour, describe what currently happens when the bug is present.

Then, note down the Version # and you’re done!

Happy bug hunting :-)


About the writer

Tina Xhemalallari is our Delivered Quality Guarantee. With more than 8 years of experience in Quality Assurance.

She writes and executes test plans based on Requirements and Use Cases, preventing bugs and developing guidelines, processes and user manuals. A BS in Computer Science from SunyIT at Utica-Rome, she is a relentless globetrotter.