Cristina M.
May 26 · 5 min read

Probably you encountered bug reports that are as long as this article or so short that you cannot even reproduce it. No matter if you are a developer, a quality assurance or a manager, a good written bug report can save you ton of time.

Photo by Glenn Carstens-Peters on Unsplash

We all need to understand that a bug report has to be as short as possible, and written with simple and concise words. That is all, nobody needs an essay.

I am a QA (here you can find how I got my first job) and sometimes I get reports from the clients or developers that are not explicit at all:

Bug description: Setting is saved only after reset.

What setting? Should I reset the application, the device? Well..please, tell me, how exactly can I reproduce that?

OR the classic

Bug description: Application does no work.

What did you do that it stopped working? Works perfectly fine for me..


Sometimes I get a very very long report. No spaces or punctuation, only text. Long phrases that make me forget what was it all about? Am I reading a novel? Oh wait, it is a bug which needs to be reproduced and converted to a easy to understand format.

Why should I waste time and try to add an easy to read format?

Because if I assign the issue to a developer, he’ll be bored and stop reading after the second row. As a result I’ll get the bug back in QA saying that it is solved.

What ? So fast?

Yeah, probably he’ll say that the bug cannot be reproduced (of course, he didn’t tried, and I’m not even blaming him for that), or he’ll fix another issue found when trying to reproduce the critical one that we got from clients (of course, he’ll not let me know that he fixed a totally different issue, so he can get rid of the complicated one).

The only scope of a bug report is to be easy to understand, so the developer is able to reproduce it.

The report should contain the following information:

Title: it should be short and explicit, most of the time is a summary of Actual Result

Steps to reproduce: a list with numbers or bullet points with the exact actions needed to be executed in order to catch the bug

Actual result: describe exactly what is happening after doing the steps

Expected result: explain what it should happen after doing the steps

Severity: can be Low, Medium, Major or Critical and refers to the impact of the bug

Notes: I’ll add here any information that I consider useful for the reproduction of the bug. Device, operating system, browser name and version are some of the details that I consider important. For desktop applications the build number is also added. This part could be specific to each project.

Attachment: video or photo

Except UI bugs, where a photo is explanatory enough, I personally like to add short videos with the steps, it saves a lot of time and developers have no excuse to send the bug back with the reason that they cannot reproduce it. I create the videos without sound and no longer than 1 min or 1 min and half, as that is long enough to execute the reproduction steps, and short enough to not loose the attention of the viewer.

Some people add gifs. I do not like that, especially for longer scenarios, because you cannot pause it. It’s going in the loop for a while until I can understand what is there.

Also I like to add the error that the console throws, or at least keep that open while creating the screen record so it will be easier to debug and understand why that scenario fails.

Now let’s see a practical example

First example: DON’T

Photo by Kai Pilger on Unsplash

Title: Application not working as it should


  1. Open the online shop
  2. Add a product to the favorite list

Actual: Product is not added

Expected: Application should work correctly

Severity: Critical

Notes: Tested on my local computer

First, the title is very general, it should be more specific and refer exactly to the bug that is described.

Second, the steps are not clear enough, the bug may be related to specific buttons or products and the bug does not state what buttons to click.

Third, actual result could be more detailed. Does it throw any error, is the user redirected or is the button even clicked?

Fourth, a critical severity refers to a defect that shuts down the system. Lets not create panic, you should add Critical severity only if that application is down or something like that.

Fourth, add exactly what should happen after doing those steps. Correctly can mean different things to every person. You should have a requirement from the client that states what correctly means for that particular application, so please use that as an expected result. The bug may be fixed in a wrong way if we use such a general statement in the expected results.

Last, be more specific about your computer: OS and browser used.

Let’s see the correct example now:

Example number 2: DO

Photo by Carlos Alberto Gómez Iñiguez on Unsplash

Title: Error is displayed when adding a product to favorites list


  1. Open the online shop (add the name/link to the shop if the team is working on multiple projects)
  2. Search for iPhone XR
  3. Select the product
  4. Press on Add to favorites button

Actual: ‘Error’ message is displayed on the screen and the product was not added to the favorites list

Expected: ‘Successfully added to your list’ message is displayed and user can find the product in the favorite list

Severity: Medium

Notes: Tested on Windows 10, Chrome 74.0.3729.169

Which of the reports would you prefer to get? I definitely want the second one.

I hope the article was useful for you and you’ll save a lot of time using this bug report template. Thank you!

The Startup

Medium's largest active publication, followed by +504K people. Follow to join our community.

Cristina M.

Written by

My name is Cristina, I am passionate about writing, finances and technology. You can find more on

The Startup

Medium's largest active publication, followed by +504K people. Follow to join our community.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade