How to create an effective bug report

Digital Natives
Sep 9, 2016 · 5 min read

Bug reports. I think I speak for all testers when i say that this is one of the most important parts of our job. I wanted to cover the notion of ‘a good bug report’ in a blog post, because over the years I’ve had the displeasure of reading and working from many bad bug reports, which can cause a sharp rise in development and testing time, which is never good news.
Let’s start with a quick crash course to bring any newbies up to scratch.

What exactly is a bug? Well, a software bug is an error, flaw, failure or fault in a computer program or system that causes it to produce an incorrect or unexpected result, or to behave in unintended ways. Like our favourite, Super Mario here. :D

What is a bug report? If bugs occur (which they certainly do), the person finding the bug, should be able to report (document & send) the bug to people in charge of fixing that error or failure.

What is a bug reporting system? A bug reporting system has many names: bug tracking software, issue tracking software, issue management software, defect tracking software and so on. Put simply, it’s a software application that keeps track of reported software bugs in software development projects.

Tools for bug tracking

You can find plenty of open source and paid tools on the internet. A little later i’ll talk you through the two i like the best — and , but you can find a pretty comprehensive list of tools . I’ll also share with you a simple bug report template to help you in creating clear and concise documents which fix faults without creating unnecessary work.

What are the most important things when creating a bug report?

There are certain things, no matter what tool you use, which you will need to cover off in order to deliver a watertight report:

  1. Found a bug? Check if the bug is known. Check whether or not the bug you are experiencing is already documented in the issue tracker.
  2. Report it immediately. Do not delay, you will forget the finer details or simply forget to report it.
  3. Reproduce the bug more than one time before you report it. Your bug should be reproducible. Make sure that your steps are robust enough to reproduce the bug without any ambiguity. If your bug is not reproducible every time you can still file a bug report but be sure to mention its sporadic nature.
  4. Make your title short and straight to the point. This is important for several reasons, first of all when the developer looks at the bug report he need to understand the problem immediately, especially when the bugfixing happens during a release. There will be no time for asking and explaining. Short and simple titles also come in handy when weeks later you have to search for your bug in your bug reporting system.
  5. Detailed summary. Identify exactly what the problem is. Saying “something is wrong” is not helpful, saying exactly what is wrong, and how to reproduce it, is. If you can tell exactly what is wrong, and reliably reproduce an example of the problem, you’ve isolated a bug. Write down the error messages too
  6. Screenshots, videos, log files. Attach them, they are useful. Especially when you have to report a bug which is barely reproducible or for a more complicated issue you can create a screen recording e.g. with OS X’s . I’m not familiar with Windows, but is a list of screen recording tools for it.

Few other things you need to take care of:

  • One bug, one bug report. Do not mix the bugs, it will confuse the developers. And it is better to file them separately so they can be tracked easier.
  • Read what you wrote. Read the report back to yourself, and see if you think it’s clear. If you have listed a sequence of actions which should produce the failure, try following them yourself, to see if you missed a step.
  • Be precise. Programmers like precision.
  • Be nice. Don’t be rude with developers, it may be their fault and your problem, and you might be right to be angry with them, but the bug will get fixed faster if you help them by supplying all the information they need. Remember, you make mistakes too.

You can download this checklist in a printable format too.

[wonderplugin_popup id=3]

Let’s check a bug report example in Nostromo and in Jira!

Here is the bug: I tried to upload a new profile picture at the Settings/Profile page. After the upload finished I got a blank page and an error message in the console. It happened in every browser I tried in. I’m working on Mac.

And how it looks like in Nostromo:


In Nostromo you can:

  • Add a title, description
  • Add members (e.g. the affected developers)
  • Add an estimation of your work
  • Create labels (e.g. to add priority, severity, belongs to which area)
  • Create a checklist
  • Attach files
  • Add comments

Jira is almost the same, there you can add some extra information and you can customise it to suit your team needs. Some other options they have:

  • Type (e.g. bug, feature, story, task, improvement)
  • Priority (e.g. trivial, minor, major, critical, blocker)
  • Affected versions
  • Components
  • Environment
  • Status

And here’s that all important bug report template I promise you. You can download it .

For me, the most important takeaway for this blog post is this — never think that writing bug report is a waste of your time. It’s a very important document which connects testers, developers and managers too. Writing a good bug report helps your company to save resources as well as create a good relationship between tester and developer.


Which tools do you use for handling bug reports?

Digital Natives

Ideation. Validation. Execution.

Digital Natives

Written by

Innovatory assistance in web development from concept to execution

Digital Natives

Ideation. Validation. Execution.