One of the first things I learned after getting into QA was that finding a bug and communicating a bug are two completely different skills.

Finding a bug is exciting! You found something broken and know it needs to be fixed.

Now comes the hard part.

You have to explain it well enough that someone else, who wasn’t sitting next to you when it happened, can understand exactly what went wrong.

When I write a bug report, I like to imagine I’m writing it for my mom. She isn’t particularly tech savvy. She’s incredibly intelligent, but technology just isn’t her thing. If she had to follow my bug report, could she reproduce the issue without calling me for help? If the answer is no, then my bug report probably isn’t as clear as I think it is.

That’s the goal. A developer shouldn’t have to ask three follow-up questions just to understand what’s broken. A good bug report should clearly explain the problem, provide enough information to reproduce it, and give whoever picks it up the confidence to start investigating.

Every company I’ve worked for has had a slightly different bug template. Some wanted screenshots. Some wanted videos. Some wanted logs. Others wanted almost nothing. The fields may change from company to company, but I think the important information stays pretty consistent.

Title

I like bug titles that tell me what the problem actually is.

Bad titles usually tell me almost nothing.

Login broken

Better titles tell me enough that I immediately understand the issue.

User cannot log in with valid credentials after resetting their password.

A good title also makes it much easier to search for duplicate bugs later.

Preconditions

Some bugs only happen under very specific conditions. Maybe the user already has to be logged in, have an active subscription, or be using an administrator account. Maybe a feature flag has to be enabled, or another setting has to exist before the issue can even occur. If there are any conditions that need to be met before someone can reproduce the bug, I try to include them. Otherwise, someone could follow my reproduction steps exactly and still never see the problem.

Steps to Reproduce

This is probably the section I spend the most time on because it’s the part that helps someone else recreate the issue. I simply document exactly what I did, step by step. If someone follows those steps, they should be able to reproduce the bug. If they can’t, then I’ve probably missed an important detail somewhere along the way.

Expected Result

The expected result is simply what should have happened. Usually that’s based on the acceptance criteria, the design, existing functionality, or documented requirements. Sometimes it’s just common sense, but either way, it’s helpful to clearly state what you expected to see.

Actual Result

The actual result describes what happened instead. I like keeping the expected and actual results separate because it makes it much easier to see exactly where things went wrong without having to compare paragraphs or infer what the problem is.

Environment

Sometimes the environment matters, and sometimes it doesn’t. If the issue only happens in Production, only in Chrome, or only on iOS, I’ll include that information. The same goes for application versions, operating systems, or anything else that helps narrow down where the bug occurs. If it helps someone reproduce or investigate the issue, it’s worth documenting.

Evidence

Whenever possible, I include screenshots or a short screen recording. Sometimes a picture really is worth a thousand words. If there are console errors, API requests, logs, or stack traces that seem relevant, I’ll attach those as well. Anything that helps provide additional context can make the investigation much easier.

Severity and Priority

Severity and priority are often used interchangeably, but they’re describing two different things. Severity is about how serious the problem is, while priority is about how quickly the business wants it fixed. A typo on a homepage might have low severity but be fixed quickly because it’s highly visible, while a more severe issue might be lower priority if it’s hidden behind a feature that very few customers use. I’ll cover those in more detail in a future article because there’s quite a bit to unpack.

Keep It Simple

One mistake I made early in my career was trying to make my bug reports sound technical. Eventually I realized nobody cared how impressive they sounded, they cared whether they were useful. If a developer has to ask several follow-up questions before they can start investigating, the bug report probably isn’t clear enough. On the other hand, if they can read it, reproduce the issue, and immediately begin debugging, then it’s done its job.

The Template I Usually Follow

Every company has its own process, but this is the template I tend to use as a starting point:

• Title
• Environment
• Preconditions
• Steps to Reproduce
• Expected Result
• Actual Result
• Severity
• Priority
• Attachments
• Additional Notes

Some teams will want more information and others will want less, but I think those sections cover the majority of bug reports you’ll write throughout your career.

Like most things in QA, the goal isn’t to write the longest bug report possible. The goal is to communicate the problem clearly enough that the next person can understand it, reproduce it, and start working toward a fix.