How to Write a Bug Report That Your Engineers Will Love

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, from the format to giving you our 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.

Good Bug Report vs. Bad Bug Report

A bug report can be likened to a user manual for assembling new furniture. A good assembly manual is helpful because it provides step-by-step instructions, clear diagrams, and labeled parts. 

Meanwhile, a bad one skips several steps and has no diagrams. The result? Extra pieces you don’t know what to do with, a throbbing headache, and a table (or what looks like a table) that you can’t use anytime soon.

A good bug report has the following characteristics: 

• Detailed: Contains all the information needed to reproduce and diagnose the issue accurately, such as detailed steps, the environment in which the bug occurs, and any relevant error messages. 
• Properly Filed and Structured: Follows proper filing and formatting guidelines.
• Clear and Concise: Communicates issues efficiently. Think of your bug report like a good tweet: You want it short, sweet, and to the point.

A bad bug report, on the other hand, lacks critical details and efficient communication. This can lead to miscommunication, longer troubleshooting times, and a slow resolution process.

Bug Report Format

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

Ideal Bug Report Template

Follow this exact format and include everything within the template to ensure you write a stellar bug report that your developers will love you for.

1. 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.

2. 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 you give testers test accounts. It’s best to include the email and password in the issue report so that when the developers discover the bug, they understand which account was used to discover it.
• 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 relies on Internet connectivity, are you using 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? In case of an intermittent occurrence, 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.

3. Steps to Reproduce A Bug

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, like “Open App” and “Login,” aren’t necessary either unless the issue relies directly upon these actions being taken.

4. 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.“

5. 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.

For example, “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 better sense of the problem and provides them with additional details to help them start their investigation.

6. 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.

7. Severity/Priority

Sharing the severity offers a degree of impact the bug has on the system’s functionality 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.) 

Recommended Approaches to Improve the Bug Reporting Process

Effective bug reports incorporate critical information and follow a standardized format to facilitate understanding and resolution. Here’s how to enhance your bug reports:

Standardize Format

If a bug report template is available for your project or within the organization, testers should make sure to follow it. A standardized format ensures consistency and that every bug log contains all the necessary details. This makes it easier for developers to understand the issue, replicate it, and work on a fix. 

Enable Testers to Provide Additional Context 

Bug reporting isn’t just about pointing out what’s wrong. More importantly, it’s about helping developers come up with a solution. Any additional context testers can provide prevents unnecessary back and forth:

• Unusual Circumstances: Any unique conditions under which the bug is observed. This helps determine whether the issue is widespread or specific to certain situations.
• Relevant Background Information: Any details that might be connected to the problem. Examples are recent system updates or changes to associated features.
• Frequency of Issue: How often does the issue occur? Does it happen consistently, sporadically, or only under certain conditions?
• Environment Details: Information regarding the software version, operating system, browser, and device being used. These are crucial for accurately replicating the bug.

Check for Duplicates 

Instruct testers to search existing bug databases for similar or identical issues before bug report submission. This avoids redundancy—developers don’t end up investigating the same problem multiple times, which wastes time and resources. Checking for duplicates also promotes teamwork. Contributors can add to existing reports, combine insights, and collaborate on solutions.

Test and Verify

Once a bug has been identified and reported, the next step is fixing it. After addressing the issue, re-test the system under the same conditions that initially exposed the bug to ensure the issue has been resolved. You’ll also want to make sure the fix doesn’t negatively impact other areas of the system or introduce any new issues.

Finally, testers should be encouraged to contact the team or person responsible for fixing the bug and provide detailed feedback on the resolution’s outcome. This closes the feedback loop and completes the bug-fixing process.

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.