How Not to Suck at Writing Bug Reports


A software tester might do several different things throughout the day, but reporting bugs is still the bread and butter of the job. A good bug report means bugs can be squashed faster, and the faster they do, the sooner the product can be declared shippable. This post will try to lay out the basic how-to’s which could prove useful to any aspiring tester, project manager, designer, or your run-of-the-mill bug aficionado.

A tester’s reality is often weird, and sanity is a valuable asset when confronted with Heisenbugs, Higgs-bugsons, and other terrifying creatures from the twilight zone of software development. Since you want to avoid playing the ol’ game of defect ping-pong and work on developing new features, knowing how to write a good bug report is an essential skill to master.

Getting counseling over software bugs

Ernest’s bug report

To help you not slide too far down the rabbit hole, I’d like to propose a framework for your QA prose. Let’s call it Ernest. Ernest is a simple framework; it’s how Hemingway would write bug reports if he were a software tester. It requires you to follow four simple rules:

1. Your bug reports should be concise

Because root cause analysis and debugging will be much faster if developers can reproduce the issue easily. This calls for clarity and completeness on your end.

2. Your bug reports should be prioritized

Because being unable to register is usually more important than padding.

3. Your bug reports should be consistently structured.

Because habit is a powerful weapon, and being consistent will ensure both you and devs follow a specific process when reporting and fixing issues.

4. Your bug report should only contain one bug.

Because bugs hate the company. If you stuff them all together, you will get tangled and won’t be able to differentiate between successfully resolved and pending issues. No one will be able to keep track of the issue at hand.

That’s it, no harder than it needs to be. They say you should learn from your mistakes, so let’s look at those first.

Breaking rule 1 with redundancy

Tester Vulgaris:

It was a bright sunny day in western Manchester when I glanced at my iPhone X and started the app. I tried uploading a profile picture using build 2.0.1-b42 when all hell broke loose and the app crashed. Fix immediately.

Breaking rule 1 with vagueness

Tester Vulgaris: Hear ye, developer, the app crashes when I start it.

Developer Vulgaris: Not on my device it doesn’t. Go bother someone else.

Tester Vulgaris: Have you tried on the Samsung Galaxy J3 with Android 6.0?

Developer Vulgaris: Oh yeah…

Lesson learned: Be like Goldilocks, never give either too much or too little information.

Breaking rule 2 with being overly dramatic and/or downright arrogant

Tester Vulgaris:

Are you expecting me to accept this fix? Everything sucks, and nothing works. Are you a developer or a clown? Maybe you should try gardening as a career choice! The hover effect on the About screen’s back button is 5% too transparent on my Samsung S3 mini. THIS IS A BLOCKER! I’m emailing you my therapist’s bill as we speak.

Lesson learned: You live in the real world, software is imperfect, and some things are more important than others. Also, don’t be a douchebag.

Breaking rule 3 with being harder to follow than Ayrton Senna

Tester Vulgaris:

I installed the latest version of the app. It was 1.0.0-b1111. I started the app. But first I cleared cache, I think. Then I immediately got a strange dialog when accessing the profile screen. It was empty. Oh yeah, the phone was disconnected from the internet. Please check that, thanks! Btw. The version of the app was actually 1.0.0-b1112. I tested on a Huawei P10, but I forgot which OS is on it. I’ll get back to you on that.

Lesson learned: You are neither a poet nor a manual writer for Ikea. You should be easy to understand, and devs should be able to reproduce the issues you report.

Breaking rule 4 by being a megalomaniac

Tester Vulgaris:

Well, I tested the latest build on 4 different devices. I found several bugs: 18 typos in the “About” section (18 screenshots and proposed corrections are attached). On one device, the app crashes if I try logging in with a legacy user. On another, the app freezes if I try sharing my post on Twitter. If you could get this done by tomorrow, that would be great.

Lesson learned: Work is best done when divided into digestible chunks. Don’t shove bug reports down people’s throats and avoid information overload.

How to do it well?

Here are some tips at sucking less at writing bug reports.


  • Should either describe the issue or explain what needs to be done
  • e.g. “The app crashes when saving a document”
  • e.g. “Remove the T&C checkbox from the registration screen.”


  • Device details: manufacturer and model, OS version, screen size, and resolution usually don’t hurt as well
  • Browser: type and version
  • Build details: exact version/build number and environment
  • Any other, e.g. your user role

The body of the bug report should contain:

  • The exact steps that need to be taken to reproduce the issue
  • The actual outcome
  • The expected outcome (possibly referring to the design, acceptance criteria, or other specs)

Useful addendums:

  • Priority (how immediately should the issue be fixed)
  • Severity (how badly it affects functionalities and/or UX)
  • Stack traces (using Crashlytics or a similar tool often comes in handy)
  • Error output from the console
  • API requests/responses when relevant
  • Screenshots of UI issues
  • Screenshots of weird UI/UX issues hard to convey in words

Here’s a fictional example that doesn’t necessarily include all of the above for the sake of brevity:

Title: The app crashes when taking a photo without camera permissions

Device: LG Nexus 5X (Android 7.0)

Build: 1.1.0-b4422

Environment: Development

Prerequisites: The test user should be a Photographer.



Start the app, and log in.


Tap on the “Create new assignment” button.


Tap on the “Take assignment photo” button.


Decline giving the app permission to use the camera

Actual: The app crashes.

Expected: When the user declines, an informative dialog with an “Ok” button should be presented.

Links: Informative dialog: Stack trace:

That pretty much wraps it up for today; now you know how to write a bug report by taking a clue from Ernest’s book. Since testing doesn’t end with pretty bug reports, in the next blog post, we’ll look at a few testing viewpoints that might help you think differently about the job you are performing. In the meantime, check out 10 principles of successful app testing.

If you find any bugs on this page, please report them to Each correctly reported bug will earn you a cup of coffee with our quality assurance team, and each improperly reported one will be exposed to hearty ridicule and relegated to the endless archives of our Gmail accounts.

Just kidding, we take bugs seriously. Ping us if you do too and have fun testing.