How to write a bug report that will make your engineers love you

Finding a bug is one thing, but documenting it is just as important, if not more so. That’s why we want to share how to write the ideal bug report. We’ll also share a list of the seven items in the Testlio bug report template.  

Bug reporting demonstrates a development issue and gives your developers a place to start fixing it. Writing a 10-page report on what you discover may be tempting, but we’ve found that the simpler and more succinct your bug report is, the better you’ll be in the long run.

As always, stick to our version of the tried-and-true KISS method (Keep It Simple, Stupid), and remember, there’s only one goal – you’ve found a bug, and now it’s time to put that bug in a conveniently sized jar. We’ll show you what our “jar” looks like.

Think of your bug report like a good tweet: You want it short, sweet, and to the point.

Top Seven List of Items Included in an Ideal Bug Report

1. [Feature Name] Title
2. Environment
3. Steps to reproduce
4. Expected Result
5. Actual Result
6. Visual Proof (screenshots, videos, text)
7. Severity/Priority

Title

Your title should serve as a concise summary of what the bug is. Our report titles start with the core feature issue in brackets at the very beginning of the title. Pro Tip: We recommend you review the title again after completing the report to ensure it is concise and reflects the problem.

Environment

The environment for every application can vary widely, but be as specific as you can. Testers should always follow the given bug report template unless otherwise specified — it helps reduce unnecessary information.

• Device: What type of hardware are you using? Which specific model?
• OS: Which version number of the OS has displayed the issue?
• Account Used: This matters if testers are given test accounts by the client. It’s best to then include email + password in the issue report. When the developers get the bug, they understand which account was used to discover the issue.
• Testing App Version: Which version number of the application are you testing? Simply writing “latest version” or “App Store Version” won’t cut it, since some bugs are version-specific, and it’s hard to know the App Store version when searching the store later – make sure your testers include this specific information.
• Connection type (if applicable): If the application you’re testing is reliant on Internet connectivity, are you on WiFi, Ethernet, or cellular data? What is the speed of the connection?
• Reproducibility Rate: How many times have you been able to reproduce the error, using the exact steps you’ve taken to activate the bug? It’s also helpful to report how often the bug has been reproduced vs. the number of attempts it’s taken to reproduce the issue, in case of an intermittent occurrence.

Steps to Reproduce

We number our steps from beginning to end so developers can easily follow through by repeating the same process. We prefer to keep step numbers relatively whittled down by using the “>” symbol.

Example description for steps to reproduce a bug:

1. Go to settings > Profile (this would take user to new screen)
2. Tap on More Options > Delete Account

This way you can provide more process information that leads to the next step without having a reproduction list that appears tediously long. Remind your testers that implied steps aren’t necessary either, like “Open App” and “Login,” unless the issue relies directly upon these actions being taken.

Expected Result

What should happen when you trigger the call-to-action? This is where you put on your end-user cap. Think about the desired outcome and offer deeper insights than “the app should not crash.“

Actual Result

Here’s the result of the bug. Does the application crash? Does nothing happen at all? Is an error displayed?

In our experience, testers can be a little vague in this department, so encourage them to be as distinct as possible and provide some information on isolation to make the bug report more actionable – “Button does not work as expected” isn’t helpful, whereas “Button closes app across different platforms, different os versions, or different screen sizes” gives developers a much better feel for the problem. It also provides them with additional details to help start their investigation.

Proof

Any pertinent screenshots, videos, or log files should be attached. Testlio bug reports usually require both a video and a screenshot, depending on the nature of the issue. If the issue requires steps to trigger the bug, then video is required. If the bug is, say, a minor UI issue that is always present, then a screenshot will suffice. Logs are also required no matter the issue.

For application crashes, we require both system logs and crash log dumps, otherwise, developers are left searching for a needle in a haystack, and this saves them valuable time.

Severity/Priority

Sharing the severity offers a degree of impact the bug has on the functionality of the system and helps the dev team prioritize their work. We recommend using one of three categories of severity in your bug report: 

1. High/Critical: anything that impacts the normal user flow or blocks app usage
2. Medium: anything that negatively affects the user experience
3. Minor: ALL else (e.g., typos, missing icons, layout issues, etc.) 

Keep reading: What does a good issue report look like?

Note how minimal our sample bug report is. We’ve seen all different types, from confusing spreadsheets, long-form bug reports that read like dissertations, to automated ones with a lot of drop-down menus. We’ve found that we prefer our reports to be short and sweet, yet informationally dense. Most engineers spend time within a problem to understand why there’s an issue and what else it impacts. However, it makes our engineers happy and efficient when they have enough information to fix the majority of bugs without having to spend valuable time isolating the incident.

That being said, it’s just as important to educate your testers on what you’re looking for, and how you’d like it to be documented. Your bug testers are your eyes and ears when it comes to weeding out issues, and just like in any good relationship, communication is key. This way you can hunt bugs in the most efficient way—together.