The most common outcome of a poorly written bug report: the developer can't reproduce the problem, marks it "Cannot Reproduce," and moves on. The bug still exists. Each element of an effective report prevents a specific failure: a precise title prevents misrouting, exact numbered steps with preconditions prevent the cannot-reproduce outcome, and separate expected vs actual results prevent developers from deprioritizing what they can't assess.

Why bug reports fail

The most common outcome of a poorly written bug report: the developer opens it, can't reproduce the problem, marks it as "Cannot Reproduce," and moves on. The bug still exists. You've wasted time. The developer is mildly annoyed. Nobody wins.

The second most common outcome: the developer reproduces it but doesn't understand the impact, deprioritizes it, and it ships to production.

Both failures are preventable.

The anatomy of a bug report that gets fixed

Title: one sentence, no vague words

The title is what appears in Jira or whatever tracker your team uses. It should tell a developer reading a list of tickets exactly what the bug is, without opening it.

Bad titles:

  • "Login bug"
  • "Something broken on the dashboard"
  • "Error message issue"
  • "Table not working correctly"

Good titles:

  • "Login form submits with empty password field: no validation error shown"
  • "Dashboard table loses sort order after filtering by status"
  • "File upload shows 'Success' toast even when upload fails with 413 error"
  • "Items table row count differs from API response when page is loaded with active filter"

The pattern: [component/feature] [what happens] [when/under what condition]. Everything a developer needs to understand the scope of the problem, before clicking to open it.

Environment: exactly where this happens

Vague: "Chrome on Windows"

Useful:

Browser: Chrome 124.0.6367.78 (Windows 11)
OS: Windows 11 22H2
App version/build: v2.4.1 (commit: abc123)
Test environment: staging (https://staging.lab.becomeqa.com)
Test user: admin@becomeqa.com

Environment details seem tedious until you're trying to reproduce a bug that only happens in Firefox on macOS and you've been running Chrome on Windows for 20 minutes wondering why it doesn't fail.

Steps to reproduce: exact, numbered, self-contained

Each step should be so specific that someone who has never seen this bug before can reproduce it on the first attempt.

Bad:

1. Log in
2. Go to items
3. Sort and filter
4. Bug appears

Good:

Preconditions: User is logged in as admin@becomeqa.com. 
The items table is displaying the default view (no active filters).

Steps:
1. Navigate to https://lab.becomeqa.com/dashboard
2. Click the "Status" column header to sort ascending
3. Click the "Filter" dropdown and select "Planned"
4. Click the "Status" column header again to sort descending
5. Remove the filter by clicking "Clear" in the filter dropdown

Expected result: Table returns to default view showing all items, 
sorted by the last sort order (Status descending).

Actual result: Table shows all items but sort order resets to default 
(unsorted), losing the sort state from step 2.

The difference: the first version requires the reader to guess what "sort and filter" means. The second version requires no guessing.

Expected vs actual result: both required, not just one

Every bug report needs both:

Expected result: what should happen according to the specification, common sense, or the developer's intent. If there's a documented requirement, reference it. "According to the acceptance criteria in PROJ-142, filtering should not affect sort state." Actual result: what actually happens. Be precise. "Shows an error" is weak, "displays 'Internal Server Error' in a red toast at the top of the page for 3 seconds" is useful.
Don't write "Expected: it works. Actual: it doesn't work." This is the most common failure mode in junior bug reports. The expected result should describe the specific correct behavior, not just "working."

Severity and priority: different things

Severity is the impact on the system: how bad is this bug technically?
  • Critical: system crash, data loss, security vulnerability, blocks core functionality for all users
  • Major: significant feature broken for a subset of users, has a workaround
  • Minor: small functional issue, cosmetic, unlikely to affect many users
  • Trivial: typo, minor UI inconsistency, no functional impact
Priority is the business urgency: how soon does this need to be fixed?

A typo on the error page of a healthcare product might be Minor severity but High priority (regulatory concern). A broken admin feature might be Major severity but Low priority (only used once a month by 2 people).

Setting severity and priority accurately signals that you understand the business impact, not just the technical behavior.

Attachments: show, don't just tell

Screenshots capture the actual result visually. A screenshot that shows the wrong toast message is worth more than three sentences describing it.

Video recordings are invaluable for timing-dependent bugs: race conditions, animation glitches, intermittent failures. Screen recording software (Loom, OBS, ShareX) takes 30 seconds to set up and prevents hours of "cannot reproduce."

Network logs (from browser DevTools → Network tab) are critical for API-level bugs. They show exactly what request was sent, what response came back, and timing.

Console logs often contain the error that explains the bug. Developers can spot the root cause immediately from a JavaScript error stack trace.

For intermittent bugs, record a video on the first reproduction. Don't assume you'll be able to reproduce it again for the developer.

A complete example

Here's what a well-written bug report looks like:

---

Title: File upload modal shows "Upload successful" toast when file exceeds 5MB size limit Environment:
  • Browser: Chrome 124, Firefox 125
  • OS: Windows 11
  • Build: v2.4.1
  • Environment: staging
Preconditions: User logged in as admin@becomeqa.com Steps to reproduce:

1. Navigate to https://staging.lab.becomeqa.com/dashboard

2. Click "Upload File" button

3. Select a file larger than 5MB (e.g., a 10MB .pdf)

4. Click "Upload" in the modal

Expected result: Upload fails with a validation error: "File size must be 5MB or less." The file is not uploaded. The success toast does not appear. Actual result: Modal closes, "Upload successful" toast appears briefly. On navigation to Files section, the file is not present, indicating upload failed silently. No error is communicated to the user. Severity: Major. Users lose their upload without any feedback, and may not realize the file wasn't saved. Priority: High. Affects any user trying to upload files over the size limit. Attachments: [screenshot showing success toast] [network log showing 413 response]

---

This report gives a developer everything: exact reproduction, clear expected/actual comparison, accurate severity assessment, and evidence.

Common mistakes to avoid

"It's not working" without saying what should happen. Always specify expected behavior. Steps that assume knowledge. "Log in as an admin." Which admin? What URL? What credentials? Missing the preconditions. Bugs that only happen with certain data, certain user roles, or after certain previous actions need that context in the preconditions section. One-line titles. "Payment bug filed." Filed against what scenario? Severity inflation. Calling everything Critical makes Critical meaningless. Reserve it for data loss, security issues, and features completely broken for all users. No cleanup of test data. If your reproduction steps created test data (a new user, an order, a file), note it so someone can clean up without a database admin.

FAQ

Should I write bug reports for every issue I find?

Log everything that isn't working as intended. Developers and product owners can close or deprioritize, but they can't fix what they don't know about. The exception is things you're not sure are bugs: raise them in a comment or a quick message first.

What if I can't reproduce the bug consistently?

Still log it. Note in the bug report: "Intermittent: reproduced 3 out of 10 attempts. Could not identify consistent trigger." Attach a video of one reproduction. An intermittent bug that's logged is better than one that isn't logged at all.

How detailed should reproduction steps be?

Detailed enough that a developer who just joined the team could reproduce it without asking you a single question. If you're unsure, err on the side of more detail.

My bug got marked "by design." Was I wrong?

Not necessarily. "By design" means the product owner decided the current behavior is acceptable. That's a legitimate outcome. What matters is that you documented the behavior clearly. If it's causing user confusion, that conversation should happen before the product decision is made, not after.

→ See also: How to Write a Test Case: Format, Examples, and Common Mistakes | What Is Manual Testing? The Complete Guide for 2026