How to raise an awesome bug report

Excellent, one of your test cases has failed, and you have exposed a defect in the application that needs to be corrected ASAP. Time to raise a bug report for the developers to action.

But before you load up your bug tracking software and hit that Create New Issue button. Ask yourself… is this a bug? And how can you best highlight this so it gets the attention it deserves by the development team? 

Take a step back

Try to reproduce the issue first and rule out the possibility of the error being caused by an error on your part or the caused by the environment that you are using to run your tests. This may seem like an obvious step but it’s critical to perform, so that effort isn’t lost in raising issues for things a user error caused such as an incorrect button being pressed.

Has the issue previously been raised already by another tester?

If you’re satisfied that you have found an issue with the software you should take the time to look through the list of already reported bugs and see if yours is listed already. Raising duplicate issues is another huge time waster for developers, and it can frustrate them if they have to investigate and fix one issue. Only for it to be included in several more tickets.

However, read the comments on the ticket and then contribute any details from your findings that would help the developer to get the issue corrected.

Anatomy of a bug report

If you have completed the above steps and you’re certain that it is a reproducible and unreported issue. Hit that new issue button!

Depending on the particular bug tracking system you are using for your project (Jira, Bugzilla, BugHunt etc). There will be different mandatory fields for you to fill in every time a new bug is submitted to the system.

But whatever the application you are using, I believe a bug report at its core is best compiled using the following elements:

  • Title.
  • Description.
  • Steps to reproduce.
  • Expected results,
  • Actual results.
  • Supporting documents.
    • Screenshots.
    • Videos.

Depending on how you use these elements to compose your bug reports can mean that your submissions will either leave the developers feeling annoyed and frustrated or clearly understand the issue you are reporting and lead quicker turn-around times back to the QA team.

Let’s look at each of these elements and I will give examples on how to use each one.


This is the part of the ticket that should describe the issue descriptively to anyone that sees it. The reader will probably see your report title in a list of other report issues and will probably be inclined to investigate those first that tells them the most detail about the issue being reported and doesn’t require guesswork to figure out what you are trying to explain.

You should also try to keep the title as precise as possible while trying to not make it overly long. Also, try to avoid using phrases like “it’s broken” or “x isn’t correct”.

  • What isn’t working?
  • What were you trying to do?
  • Where was the error discovered?


This is the part of the issue in which you can go in further detail that was isn’t present in your title. Examples of these would include:

  • Environment details.
  • Specific project details, such as the version of the software.
  • Links to any supporting details or queries.

Use this area to provide as much information as you can to the developers about the error to increase the likelihood of it being reproducible in the same environment and circumstances as which you discovered it.

Steps to reproduce

If you can’t tell someone how to reproduce your steps to an error that you have found. Have you found a bug in the software?

I don’t think so. Which makes getting this part of the report critical to any report submitted.

Listing out each step to be taken in a numbered format makes it easy to tell what actions they should perform at each step and the sequence they should perform them in. Try not to miss out any steps thinking something may be obvious. If you had to enter a message in a form to make it validate, for example. Make sure it is included.


  1. Navigate to ‘Contact Us’ from the home page.
  2. Scroll down to the contact form and enter a message.
  3. Press the submit button.

Actual results

Actual and expected results can sometimes occur before each other in a report. But the main function of the actual results section is to describe the outcome of your performed steps and the bug that is occurring.

Again, try to be as specific as possible and try not included vague phrases like ‘the result is is wrong’.

Expected results

Take a moment before filling in this section of the report to be clear on how the actual results differ from what you expected to occur.

Bugs can sometimes be described as features of the application, so if it’s not clear to the reader on how your results show a bug. It is likely to be described in this way due to them not knowing how to ‘fix’ it.

Supporting documents

It is a requirement in most circumstances to include supporting documents to further aid in highlighting the issue to the development team.

This would take the form of a quick screenshot of the bug and a video of you reproducing the bug with screen-capture software.

Finally, before submitting your report. Read over the issue and ensure you are not accusing the developer of wrongdoing and being negative about their efforts.

Testers and developers are part of the same team and we should work with one another to help produce the best quality software that the end-users deserve. Highlighting bugs to developers is one of the best ways that we as testers can help to achieve that end goal.

Developers will be much more appreciative of your efforts if the bug report is of high quality and includes the above details.

Once it is submitted and is with the development team. Remember to be proactive and find out the current status.

  • Is it being looked at?
  • When will it be back with the test team?
  • Do you need any other information?

Of course, try not to be annoying with this!

Finally, if you think something is a bug, make sure that it gets reported. It’s better to raise something and people to be aware of its presence. Then to not raise it and let it be discovered by your users.

Edit: I have included a full example of a badly written report and a awesome report in a PDF which is located here.

If there are any further questions, please let me know!

Posted by Kevin Tuck

Kevin Tuck is an ISTQB qualified software tester with nearly a decade of professional experience. Well versed in creating versatile and effective testing strategies. He offers a variety of collaborative software testing services. From managing your testing strategy, creating valuable automation assets, or serving as an additional resource.

2 Replies to “How to raise an awesome bug report”

  1. Hi Kevin,
    Thanks for a nice article. Could you provide some template in pdf?


    1. Thank you for the comment!

      Sure of course. Here is a PDF.


Leave a Reply