Bug Report Template: How to Write a Great Defect Report

Developers fix what they can reproduce; adjectives and urgency labels alone do not ship patches. How to write a bug report that gets fixed focuses on what failed, where, exact steps, expected vs actual, and why it matters, so the defect does not die in "cannot reproduce" ping pong.

This guide gives you a practical bug report template, field by field instructions, severity versus priority guidance, before and after examples, evidence tips, and common mistakes. You can use it in Jira, Linear, Azure DevOps, GitHub Issues, or a spreadsheet.

What Is a Bug Report?

A bug report, also called a defect report, is a structured record of observed incorrect behavior in software. It documents the conditions, steps, expected result, actual result, impact, and evidence needed to investigate and fix the issue.

A bug report is different from a test case. A test case defines how to verify expected behavior. A bug report records a failure found during that verification or during exploration. If you need both skills, pair this guide with how to write test cases.

A bug report is also different from a vague complaint. "Checkout is broken" is a signal. A bug report turns that signal into an actionable engineering artifact.

Why Bug Report Quality Matters

High quality reports:

• Reduce time to first useful developer action.
• Improve fix accuracy on the first attempt.
• Create a searchable history of product risk.
• Support release decisions with real evidence.
• Teach the team where tests and requirements are weak.

Low quality reports:

• Generate "need more info" loops.
• Get closed as cannot reproduce.
• Hide multiple bugs inside one ticket.
• Inflate defect counts without improving quality.
• Damage trust between QA and engineering.

In many teams, the difference between a junior and senior tester shows up first in defect communication.

Bug Report Template with Steps to Reproduce

Use this template as your default.

Title:
ID / Key:
Product / Module:
Environment:
Build / Version:
Browser / Device / OS:
URL / Screen / API endpoint:
User role:
Severity:
Priority:
Status:

Summary:
Preconditions:
Test data:
Steps to reproduce:
  1.
  2.
  3.
Expected result:
Actual result:
Impact:
Workaround:
Attachments / evidence:
Related stories / requirements / tests:
Notes / questions:

Copy Friendly Minimal Version

If your tracker has custom fields, still ensure these exist somewhere in the body:

Title:
Environment + build:
Steps:
Expected:
Actual:
Evidence:
Severity / priority:

Field by Field: How to Write Each Part

Title

The title is a search result and a triage headline. Make it specific.

Weak titles:

• Login issue
• Button not working
• Payment bug
• Weird error

Strong titles:

• Login shows 500 error when password contains trailing space
• Apply coupon button remains disabled after valid code entry on mobile Safari
• Invoice PDF exports previous order totals after customer switches account

A good pattern:

[Where] [what fails] [under what condition]

Summary

One or two sentences that restate the failure and impact.

Example:

Environment

Bugs often depend on environment. Include:

• Test, staging, production, or local.
• Build number or commit.
• Browser and version.
• OS and device.
• Feature flags if known.
• Region, locale, or timezone when relevant.
• API environment or tenant.

Example:

Environment: Staging
Build: web-1.18.3-rc.2
Browser: Chrome 126
OS: macOS 14.5
Role: Buyer
Flag: checkout_v2 = on

Preconditions

State what must already be true.

Examples:

• User is logged in as a verified buyer.
• Cart contains one eligible item.
• Coupon SAVE20 is active and unused for this user.
• Wallet balance is 0.

Missing preconditions are a top cause of cannot reproduce.

Test Data

Include the exact values that matter. Mask secrets, but do not hide the structure of the data.

Good:

User: buyer.reload@example.com
Product: SKU-114 (in stock)
Coupon: SAVE20
Payment method: Test card 4242

Avoid:

Use a normal user and some coupon.

Steps to Reproduce

Numbered steps. Observable actions. No mind reading.

Weak steps:

1. Go to checkout
2. Try coupon
3. See bug

Strong steps:

1. Log in as buyer.reload@example.com.
2. Add SKU-114 to the cart.
3. Open checkout.
4. Enter coupon code SAVE20 and apply it.
5. Confirm the discount shows 20 percent once.
6. Refresh the browser page.
7. Observe the order summary discount and payable total.

If the bug is intermittent, say so and include approximate frequency, timing, or race conditions you noticed.

Expected Result vs Actual Result

This pair is the heart of the report. Write both explicitly.

Expected result describes correct product behavior according to requirements, design, or reasonable user expectation when requirements are silent.

Actual result describes what the software did.

Weak:

Expected: works
Actual: does not work

Strong:

Expected result:
- Coupon remains applied once after refresh.
- Discount amount stays 20 percent of eligible subtotal.
- Payable total does not decrease again.

Actual result:
- After refresh, discount lines appear twice.
- Payable total is reduced by 40 percent.
- Order review page shows duplicated coupon row.

Learning how to write clear expected vs actual results prevents arguments about whether something is "really a bug."

Impact

Impact explains why someone should care.

Examples:

• Users cannot complete purchase.
• Admin can view another tenant's invoices.
• Report totals are wrong for finance export.
• Accessibility: keyboard users cannot dismiss modal.
• Data loss: unsaved draft disappears without warning.

Impact connects technical failure to product risk.

Severity vs Priority in Defect Reporting

Teams often mix these fields. Keep them distinct.

Examples:

Suggested severity scale:

1. Critical / Blocker: crash, data loss, security breach, main flow completely blocked.
2. Major / High: major feature broken with no practical workaround.
3. Medium: important feature impaired, workaround exists.
4. Low / Minor: limited impact, cosmetic or edge issue.
5. Trivial: polish nits with negligible user harm.

Priority labels vary by tool (P0-P3, High-Low). Align with team definitions and do not invent personal scales mid-release.

Evidence

Attach what shortens investigation:

• Screenshots with the failure visible.
• Screen recordings for interaction bugs.
• HAR files or network logs for API failures.
• Console errors.
• Server correlation IDs if available.
• Database or response payloads in staging, redacted as needed.
• Comparison screenshot of expected design when visual.

Name files usefully:

checkout-duplicate-coupon-after-refresh.mp4
invoice-idor-userA-sees-userB.png

Workaround

If users or testers can bypass the issue, document it. Workarounds affect priority and support guidance.

Example:

Related Links

Link to:

• User story or requirement.
• Figma or design.
• Test case ID.
• Previous related defects.
• Pull request if already suspected.

Traceability helps fix verification and future regression design.

Defect, Bug, and Failure: Practical Language

You will hear these terms used loosely.

• Failure: the system behaved incorrectly during observation.
• Defect / bug: the underlying flaw that caused or can cause failures.
• Error: often used for human mistakes in code or requirements, depending on the textbook.

In daily work, write clearly about observed behavior first. Terminology debates do not fix production. Still, knowing the distinctions helps in interviews and process docs inside the software testing life cycle.

How to Write a Bug Report Developers Will Act On

Rule 1: Make It Reproducible

If you can reproduce it, write the shortest reliable path. If you cannot reproduce it consistently, say that and provide patterns:

Intermittent: failed 3 of 10 attempts
Appears more often on slow 3G throttling
First noticed after enabling checkout_v2 flag

Rule 2: Report One Problem per Ticket

Do not combine unrelated issues:

• Coupon duplication
• Footer typo
• Dark mode contrast problem

Those are three tickets or one ticket plus linked nits, depending on process. Mixed tickets create partial fixes and messy retests.

Rule 3: Separate Facts from Interpretation

Facts:

Interpretation:

Both can be useful, but label hypotheses as notes, not as proven root cause.

Rule 4: Use Product Language for Impact

Developers can inspect stack traces. They still need product context:

Rule 5: Be Respectful and Specific

Avoid:

Prefer:

Tone does not replace rigor, but bad tone slows collaboration.

Full Example: Weak vs Strong Bug Report

Weak Report

Title: Payment broken
Steps: try to pay
Expected: success
Actual: error

This will bounce.

Strong Report

Title: Saved card checkout returns 500 on mobile Chrome when CVV is empty by design

Environment: Staging, build web-1.18.3-rc.2
Browser/Device: Chrome 126 on Pixel 7, Android 14
Role: Returning buyer with one saved Visa

Preconditions:
- User has a saved card on file
- Cart has SKU-114
- Feature flag saved_cards_v2 is enabled

Steps to reproduce:
1. Log in as buyer.savedcard@example.com.
2. Add SKU-114 to cart and open checkout.
3. Select the saved Visa ending 4242.
4. Leave CVV blank if the field is shown, or proceed if CVV is not requested.
5. Tap Pay now.
6. Observe the result and network response.

Expected result:
- Payment either completes successfully for a vaulted card flow that does not require CVV, or the UI blocks submit with a clear CVV required message.
- No unhandled 500 error.
- User sees a recoverable state.

Actual result:
- UI shows generic "Something went wrong".
- Network tab shows POST /api/payments/charge -> 500.
- Request ID: pay_9f3c2a.
- User remains on checkout with cart intact.

Impact:
- Returning mobile users cannot complete purchase with saved cards.
- Potential mobile conversion loss.

Severity: Critical
Priority: P0
Evidence: screenshot + HAR + 15s screen recording attached
Related: story PAY-221, test case TC-PAY-014

The strong report is longer, but it saves multiple conversation cycles.

Special Bug Types and How to Report Them

Visual Bugs

Include viewport size, browser, and expected design reference. Mark if it is cosmetic only or if it hides functionality.

Data Bugs

Include record IDs, before and after values, and whether refresh or re-login changes the result.

Permission Bugs

Include both roles used, exact resource IDs, and whether horizontal or vertical privilege is involved. Security issues may need private handling.

Performance Bugs

Include timing measurements, environment load conditions, and whether the issue is lab only or user visible. Avoid "feels slow" without numbers when possible.

List page took 9.8s to become interactive on staging with 20k projects for this tenant.
Expected under current SLO: under 3s for this dataset size.

Intermittent Bugs

Capture frequency, logs, and any correlation with concurrency, cache, or network. Do not overclaim certainty.

Regression Bugs

State what used to work, when it last worked if known, and whether a recent deploy or feature flag correlates. This helps bisect.

Lifecycle of a Bug After You File It

Typical flow:

1. New / open
2. Triaged (severity, priority, owner)
3. In progress
4. Fixed / ready for retest
5. Verified or reopened
6. Closed

Your job after filing:

• Answer clarification quickly.
• Retest on the build that claims the fix.
• Add a regression test case when the risk deserves it.
• Close with evidence, not hope.

For suite placement after fixes, see smoke vs sanity vs regression testing. Many fixes need a sanity retest plus a long term regression case.

Writing Bugs Found in Exploratory Testing

Exploratory sessions produce notes first, tickets second. During a session, capture raw observations quickly. After the session, convert solid failures into clean reports.

Session note:

11:20 checkout refresh doubled coupon, total wrong, screenshot 4

Ticket later: full template with polished steps.

Do not file twenty half-written thoughts as defects. File confirmed issues and keep questions in session notes. More on that craft in the exploratory testing guide.

Bug Report Review Checklist

Before you click Create:

• Title is searchable and specific.
• One issue only.
• Environment and build are present.
• Preconditions and data are enough to start.
• Steps are numbered and complete.
• Expected and actual are both explicit.
• Impact is clear.
• Severity is justified by impact.
• Priority suggestion matches release context if you provide one.
• Evidence is attached and readable.
• Secrets are redacted.
• Related story or test links are included when known.
• Intermittent nature is stated if applicable.
• Tone is professional.

Common Mistakes When Writing Bug Reports

Mistake 1: Vague Titles and No Actual Result

If the title is "issue" and the body says "not working," nobody can triage well.

Mistake 2: Missing Environment Details

Many defects exist only with a flag, role, browser, or tenant. Omit those and you invite cannot reproduce.

Mistake 3: Expected Result Copied as Wishful Thinking

Expected results should map to requirements or agreed behavior. If requirements are silent, say what you assumed and ask for product confirmation.

Mistake 4: Steps That Start in the Middle

"Click save again" is useless without the path to the screen and the data already entered.

Mistake 5: Severity Inflation

Marking every bug critical trains teams to ignore severity. Protect critical for true blockers and severe harm.

Mistake 6: Logging Opinions as Facts

"This is ugly" may be valid UX feedback, but design feedback and functional defects should be labeled clearly.

Mistake 7: No Evidence for UI or Timing Issues

A short recording can replace five paragraphs. Attach it.

Mistake 8: Closing Without Retest Notes

When verifying a fix, write what build you tested and what you checked. Future readers need that trail.

Team Conventions That Improve Defect Quality

• Shared severity definitions in the wiki.
• Required template fields in the tracker.
• Example of a great report pinned for new hires.
• Private security defect path.
• Tagging for regression, blocker, data-loss, security.
• Weekly triage so tickets do not rot.

Templates do not replace thinking, but they prevent avoidable omissions.

Collaboration Patterns That Speed Up Fixes

During Triage

Join triage with facts ready:

• Can we reproduce on latest build?
• Is there a workaround?
• Who is affected (all users, one role, one browser)?
• Did this start after a known deploy?

If you cannot attend triage, put those answers in the ticket so decisions do not wait on you.

During Investigation

Developers may ask for more logs or a narrower reproduction. Respond with updated steps rather than rewriting history silently. Add a comment:

Update: reproduced on build 1.18.4 as well.
Narrowed steps: refresh is not required if the user opens checkout in two tabs and applies the coupon in both.
New evidence: recording-2.mp4 attached.

During Retest

When a fix returns:

1. Deploy or select the build that claims the fix.
2. Run the original steps exactly.
3. Run at least one nearby path if the fix was risky.
4. Record pass or reopen with fresh evidence.
5. Link any new regression case you added.

Retest comments should include build ID. "Looks good" without a build is weak history.

Writing Bugs for APIs and Backend Failures

UI is not the only place defects appear. For API issues:

Title: POST /api/orders returns 500 when shippingCountry is IN and cart has mixed tax categories

Environment: staging API gateway
Auth: bearer token for buyer role
Request:
  method: POST
  path: /api/orders
  body: { ...minimal failing payload... }
Expected: 201 with order id, or 422 with validation details if business rule forbids mix
Actual: 500 with request id ord_41af
Impact: checkout cannot complete for mixed tax carts in India

Include headers that matter (content type, auth style), minimize the payload, and never paste production secrets.

Accessibility Defects Deserve Clear Structure

Accessibility bugs are real product defects. Write them with the same rigor:

Title: Checkout pay button is not keyboard reachable when promo drawer is open
Steps:
1. Open checkout with keyboard only.
2. Open promo code drawer with Enter on the promo control.
3. Attempt to Tab to Pay now.
Expected: Pay now remains reachable or drawer manages focus with a clear close action and returns focus.
Actual: Focus cycles inside drawer controls only; Esc does not close; mouse is required to pay.
Impact: Keyboard users cannot complete purchase when promo UI is open.
Severity: High
Evidence: screen recording with focus outlines visible

Mention assistive tech only when you used it (for example NVDA). Do not guess screen reader behavior you did not observe.

Templates for Different Trackers

Jira Style Fields Mapping

GitHub Issues Style

Use markdown headings in the body so scanners and humans can parse quickly:

### Summary
### Environment
### Steps to Reproduce
### Expected
### Actual
### Impact
### Evidence

Chat First, Ticket Second

If you report in Slack under pressure, still create the ticket within minutes. Chat scrolls away. Tickets become history, metrics, and release evidence.

How Bug Reports Feed Better Testing

Every serious defect is a signal about missing coverage. After verification, ask:

• Should a regression case exist?
• Should automation cover this path?
• Was the requirement unclear?
• Did environment gaps hide the issue earlier?
• Should smoke or sanity include a related check?

This closes the loop between defect reporting and prevention. Without that loop, teams only get faster at writing tickets for the same class of failures.

Practice Exercise

Take any public demo site and find one real issue or limitation. Write a full report using the template. Then rewrite the title three ways and pick the most searchable one. Compare your steps with a teammate: if they cannot reproduce from your text alone, strengthen preconditions and data.

Second drill: rewrite a weak historical ticket from your team (redact names) into the strong template. Measure how many questions disappear.

For timed practice with feedback loops, use a QABattle battle on the manual track. Convert one failed observation into a ticket quality report, not only a chatty note.

Final Practical Workflow

When you find a failure:

1. Pause and preserve evidence.
2. Reproduce at least once more when possible.
3. Minimize the steps.
4. Capture environment and data.
5. Write title, expected, actual, and impact.
6. Attach proof.
7. Set severity carefully and suggest priority if your process expects it.
8. Link requirements or tests.
9. File the ticket and notify if it is a blocker.
10. After the fix, retest, update the ticket, and add regression coverage when needed.

If you remember one line, remember this: a bug report is a reproducibility contract. The easier you make correct understanding and exact reproduction, the faster the product improves. That is the real skill behind how to write a bug report well, and it compounds across every release you touch.