Your automated tests just finished running. The latest deployment had only minor changes, so you expected no issues. Instead, three tests failed. When a user clicks the “My Profile” button, nothing happens. It’s time to notify the development team and write a bug report.

A bug report is a structured document that describes a software defect, including what went wrong, how to reproduce it, and the context developers need to fix it quickly. It is often the first—and sometimes only—input engineering receives, and the primary artifact used to assess severity, risk, and prioritization.

Strong bug reports are complete but concise. They clearly describe the issue, provide relevant context, and connect related failures to show patterns or regressions. Weak reports obscure the root cause, omit critical details, and force developers to repeat investigation work.

This guide explains the four essential elements every bug report must include, the additional context that supports prioritization, and best practices that speed up resolution.

4 essential elements every bug report must include

A complete bug report requires four essential elements: expected and actual results, steps to reproduce the bug, video replays or screenshots of the issue, and browser logs. Together, these elements help developers pinpoint the issue, identify the root cause, and fix the problem quickly.

Expected and actual results

This is the essence of a bug report, so clarity is key. Whether you're doing manual or automated testing, you should have a test matrix or outline that describes any test's expected result. If the actual behavior differs (in other words, if there's a bug), be detailed about what happens and when. It may not always be obvious what caused a bug, so the more detailed the information, the easier for a developer to analyze the root cause.

Reproduction steps

Some of the sneakier bugs only appear if they're triggered in a very specific way. That's why a step-by-step guide outlining the reproduction steps is essential. When a developer doesn't see the same result that a tester saw, they have to go hunting for additional context—back-and-forth that might take hours—which is time spent blocking a release (best case) or affecting real users (worst case).

When writing out repro steps, be descriptive but brief. Format them as a numbered, sequential list of actions, starting from a known state (like "logged in as admin user"). Include specific details like button names, field values, and expected wait times.

Example reproduction steps:

1. Navigate to /profile
2. Click the "Edit Profile" button in the top right corner
3. Change the email field to test@example.com
4. Click "Save Changes"
5. Error message appears instead of success confirmation

Video or screenshot evidence

A picture is worth a thousand words, and a video is even better. The additional context helps the developer follow along with the repro steps, and it's easier to convey tiny details visually than try to write them out. Since many apps have very similar pages and different people refer to them by different names, having a video is like having a GPS instead of a paper map.

Browser logs and technical details

Some bugs can only be found by peeking behind the scenes. The console logs, whether presented within the video or as separate screenshots, provide a technical trail that reveals the errors encountered by the user. These logs serve as valuable clues for diagnosing the root cause of the issue. 

Advanced bug report elements: Severity, environment, and context

To elevate your bug report from good to great, include these three contextual elements that help engineering teams prioritize fixes and allocate resources effectively. Engineering time is scarce and expensive. These details help PMs, engineering managers, and developers weigh the costs and benefits of shifting effort from product development to bug squashing.

Severity classification

Bugs come in different shapes and sizes. Categorizing the severity level—usually low, medium, high, or critical—guides the urgency and priority of bug resolution. Your team should define these thresholds explicitly because impact standards vary by product, userbase, and revenue model; the categories below are an example framework.

How to determine bug severity:

• Critical: Blocks core functionality, prevents user authentication, or impacts revenue directly
• High: Major feature is broken, but workarounds exist
• Medium: Feature partially broken or affects subset of users
• Low: Cosmetic issues that don't affect core user experience

Purely cosmetic UI bugs that don't affect the core user experience or impact revenue may not be worth pulling resources from other projects to fix immediately. In contrast, a bug in the authentication flow would prevent anyone from using the product and must be fixed before any other work gets done.

Affected environment details

Software behaves differently in various environments. Specifying which environments are affected by the bug—whether all or a subset—helps determine whether the bug is a widespread issue or confined to specific conditions. This context is pivotal in gauging the severity and scope of the bug.

Include details like:

• Browser type and version (Chrome 120, Firefox 115, Safari 17)
• Operating system (Windows 11, macOS Sonoma, iOS 17)
• Environment (local, staging, production)
• Device type (desktop, mobile, tablet)

A bug discovered in a local branch shouldn't necessarily stop the build from graduating to the next environment. But a bug in staging should be blocked from going out to production. 

Related test cases and impact

Often, a single bug will affect multiple tests in a suite. Identifying them and connecting the dots for the engineering team can help pinpoint the root cause of the issue, but it can also change the severity and priority. When a bug blocks a large portion of a test suite from running, the missing test coverage creates opportunities for other bugs to escape. What started as a small P3 problem has the potential to let unrelated P0s escape because the test suite can't check the whole product.

Additional best practices for bug reporting

These additional practices can further improve bug resolution speed, team collaboration, and take your bug report from an A- to an A+.

Links to communication channels

Bug reporting is all about sharing information. Having a direct line of communication between testers and developers simplifies collaboration. Include links to relevant Slack threads, GitHub discussions, or Jira tickets where the issue has been discussed. This prevents duplicate conversations and ensures everyone has access to the full context.

Remedy attempts

These can be included in the video or as a written note on the bug report. They're always helpful to demonstrate the bug in action—and a good double-check for the tester to make sure that the bug is consistently reproducible. Document what you tried to work around the issue, whether clearing cache, trying different browsers, or testing with different user accounts. This information helps developers rule out environmental factors.

Bug report template

Use this template to ensure you include all essential elements:

Bug title: [Brief, descriptive title]

Severity: [Critical/High/Medium/Low]

Environment:

• Browser: [Chrome 120, Firefox 115, etc.]
• OS: [Windows 11, macOS, etc.]
• Environment: [Local/Staging/Production]

Reproduction steps:

1. [First step]
2. [Second step]
3. [Continue...]

Expected result:
[What should happen]

Actual result:
[What actually happened]

Video/screenshots:
[Attach or link to visual evidence]

Console logs:
[Attach logs, HAR files, or Playwright traces]

Related issues:
[Link to related bugs or affected test cases]

Additional context:
[Communication links, remedy attempts, or other relevant information]

Great testers write great bug reports

Crafting a comprehensive bug report goes beyond just describing an issue—it's about effective communication and collaboration. By incorporating video demonstrations, clear step-by-step instructions, logs, environmental context, severity assessment, and related test details, QA testers empower developers with the insights to diagnose and resolve bugs swiftly. A well-structured bug report streamlines the debugging process, fosters efficient teamwork, and enhances software quality and user satisfaction.