What's in a good bug report

Bug reports are about conveying information. That information is being used to answer a few really simple questions:

  • What is going on?
  • Where/When does it happen?
  • What are some clues to the root cause?

If those three things can be conveyed in a bug report, I would consider it "good". It's enough information that whatever engineer picks up the ticket should be able to read through it, understand the issue, when/where it might be occuring and then get some context for why it might be happening. Having a clear understanding of an issue is not only going to speed up the resolution time, but it's also going to help better understand the severity and impact.

The key elements of a good bug report are:

  1. Title
  2. Description
  3. URL
  4. Screenshot/Video
  5. Logs
  6. Browser Metadata
  7. Device Metadata
  8. Nice to haves your developers will love ❤️
user bug report screenshot github
User Bug Report automates bug report creation.

Title

Obvious beats eloquence. Go with something straightforward. Remember that often times your team members might be non-native speakers of your company's operational language. So bear that in mind for word choices.

Description

Again keep it short, sweet and to the point. In our survey, we found that 20% of developers only read the first 3 sentences of a bug report. So bear this in mind while writing!

That said, some reports will require a lot more explanation than others—think an incorrect button color vs. an inconsistent data issue. Remember your non-native language speaking colleagues. Try to keep the language clear, direct, and to straightforward.

Key things to include in your description are:

  • Steps to reproduce the defect
  • The expected result vs. what was observed

A fun little tool you can use to test your title and description for how easy they are to understand is the WebFX Readability Test Tool. While it might not work for every situation, it's a good way to get a ballpark estimate of how your text might be received.

For example, "The button is red. It should be purple" scores a 2nd grade reading level. Whereas "The button is currently red but should be purple instead." scores an 8th grade reading level. Granted neither are Tolstoy, but if you're working with a team of non-native speakers it might be helpful (Sadly, my Spanish reading level hovers between a 2nd and 3rd grade).

device farm
WebFX Readability Test Tool: The title of this post should be easily understood by 7-8 year olds.

URL (or relavant environment information)

If found on a web application, provide the full URL to the page where the issue occurred or the details on the environment where the defect was observed. For example, did the defect occur in a dedicated test deployment or in production? In the mobile app? Web app? Both?

Screenshot/Video

A picture is worth 1,000 words. No different here. And it's no surprise that engineers rated this the #1 most helpful part of a bug report in our survey. Take the time to do a screenshot or screen capture.

Pro Tip: If you're using OSX, check out the screenshot shortcuts. Try the CMD + OPT + SHIFT + 4 shortcut to take a screenshot and automatically copy it to your clipboard.

CMD + OPT + SHIFT + 4
CMD + SHIFT + 4 copies a portion of the screen to your desktop. Add `OPT` to send it to your clipboard.

Logs

Network request logs and console logs provide clues to what might have happened. In the event of a difficult to reproduce issue, logs are invaluable. Network logs are going to help with issues that are related to resources not being found, cacheing errors, inconsistencies in deployments, etc. Console logs are a bit of a catch all but still helpful nonetheless.

Pro Tip: When grabbing console logs in the browser, make sure you have all of the log levels set for your console. This will ensure you capture any and all logs from the application.

console log chrome log level
Upping the log level increases the amount of data you'll capture.

Browser Metadata

There are inevitably cross-browser issues that your application will encounter. It could be subtle differences between Chrome and Safari, or it could be pesky IE11 issues. Whatever the case it's good to include details about the browser you were using when reporting an issue. And don't just include "Chrome" or "Safari". Be sure to add details such as the exact version, the default langauge, and anything else you find in the JavaScript window.navigator variable.

In addition, things like the display resolution and window resolution are also helpful--especially for apps that are responsive.

Device Metadata

Similar to browser metadata, device info helps identifying issues across devices. If you're reporting a web bug, you'll want to include whether or not the device was mobile, what kind of device, the pixel ratio, version, and resolution. Depending on the platform of the device, the amount of data you'll be able to capture will vary.

device farm
Device testing is tedious but important

Nice to haves your developers will love ❤️

Epoch - The time the event happened as a unix epoch style timestamp. i.e. 1606709349. Usually seconds is sufficient. If you want to include miliseconds that's fine as well.

Local Time - The time the event happened with the local time zone. In JavaScript you can simply use new Date().

Application Version - Simple yet very useful. Include the active version as either a SemVer, git hash, or whatever nomenclature your company uses.

Screenshot Markup - Channel your inner color commentator and markup the screenshot/video explaining exactly what the issue is. Draw circles, write notes, whatever it takes! You'd be surprised how difficult it can be to see what the actual issue is. A big red arrow goes a long way.

User Agent - This is an expanded version of browser metadata, but including the user agent string is helpful in case the developer working on the bug needs to parse out their own custom data.

Before you go

This might seem like a lot to capture each time you're reporting a bug. But fear not! There are tools out there (queue plug) like User Bug Repoort that do all of this for you--automatically. Check out our product if you want to automatically generate high quality bug reports.


Want to read more?
Sign up for our newsletter.