How-To: Create a Bug Report

Great! You’ve found a bug! And, wow, is it wreaking havoc! You did your homework. It’s reproducible, you know which environment it’s in, and it’s not been reported because you did your due diligence by searching through the ticketing system (insert Jira, Shortcut, Clickup, etc. here). This means you get the gold bug award.

Finding the bug is only the beginning. Here’s how to create a great bug report.

What Qualifies as a Great Report?

Information. The more details you provide, the faster the engineering team can find and fix the issue. Let’s start with the essentials.

• Browser Information: What browser are you using? Does the issue exist in other browsers?

• Environment: Was the issue discovered in production? Does the issue exist in the Staging or QA environments? Sometimes the fix is on the way and you didn’t even know! Is the opposite true? The issue is in Staging but not in Production? Being able to identify which environments the issue is helps spread awareness across teams and prioritize a fix.

• Reproducibility? Are you able to reproduce the issue when you follow a specific number of steps? Bugs that are reproducible are easier to find and fix. Intermittent bugs? Not so much.

Armed with all this information, here’s what to include in the ticket:

Form Fields:

• Expected Results

  • This describes the outcome of what should happen when a user takes a specific number of steps through the application.

• Actual Results

  • This describes the outcome that’s actually happening when a user takes those steps.

• Steps to Reproduce

  • Provide a clear numbered list that outlines where you started and what happened. For example:

1. Navigate to the homepage (include the url: this helps identify the environment you are working in)

2. Login as a client user

3. Click the profile icon

4. From the profile page, click the “Reset Password” link

5. The user is not sent to the Reset Password page

• Videos/Screenshots

  • While Steps to Reproduce may be enough, sometimes it’s more helpful to include videos or screenshots of what you are seeing. Providing visuals are a great way to bring deeper insight on the issue.

• Notes:

  • This is where you can include browser information, which environment the issue was discovered and version number of the application.

• Important Links:

  • Any conversation surrounding the issue provides context for the engineering team. These conversations can come from the communication tool the company uses (i.e. Slack or Teams) or any other source that creates a shared understanding of the issue and why it appeared.

Smash that submit button.

Now watch the magic happen.

🤔 Hmm, did I miss anything? What other information do you use in your bug reports the help provide additional information? Let me know in the comments!Till next week…