How to Write a Bug Report: Template and Best Practices

Why good bug reports matter

A vague bug report wastes time. Developers cannot reproduce it, so they close it as "can't reproduce" or spend hours asking follow-up questions. A well-written bug report with clear steps, environment details, and evidence gets triaged quickly, assigned accurately, and fixed without unnecessary back-and-forth.

Writing good bug reports is one of the most consistently underrated skills in QA.

The essential fields of a bug report

1. Title (summary)

One clear sentence describing what is broken. Use the format: [Component] [action] [expected vs actual outcome].

Bad: "Cart is broken"
Good: "Checkout - applying a discount code removes items from the cart"

2. Steps to reproduce

Numbered steps that allow anyone to reproduce the bug reliably. Be precise: include the exact values you entered, the exact sequence of actions, and the starting state required.

1. Navigate to /products/red-widget
2. Click "Add to Cart"
3. Navigate to /cart
4. Enter promo code "SAVE20" in the discount code field
5. Click "Apply"

3. Expected result

What should happen. Be specific. "Discount is applied and cart items remain unchanged."

4. Actual result

What actually happens. "Cart becomes empty after applying the promo code."

5. Environment

• Browser or device (and version): Chrome 124, macOS 14.4
• Operating system
• Test environment: staging, production, or local
• Application version or build number if known
• User role or account state if relevant: logged in, guest, admin

6. Severity and priority

Severity: the impact of the bug on the user. Critical (blocks core functionality), High (major feature broken), Medium (workaround exists), Low (minor visual or UX issue).

Priority: how urgently it needs to be fixed, often influenced by business context (e.g. a low-severity bug on the checkout page may be high priority).

7. Evidence

Screenshots, screen recordings, browser console logs (for JS errors), and network request/response captures (for API bugs). A screen recording is worth 1,000 words.

Reusable bug report template

Title: [Component] - [brief description of failure]

Summary:
[1-2 sentence description of the bug]

Steps to reproduce:
1.
2.
3.

Expected result:
[What should happen]

Actual result:
[What actually happens]

Environment:
- Browser/device:
- OS:
- Environment: staging / production / local
- App version (if known):
- User state (if relevant):

Severity: Critical / High / Medium / Low
Priority: P1 / P2 / P3 / P4

Evidence:
[Screenshot / recording / logs attached]

Additional notes:
[Any related bugs, fix suggestions, or context]

Common mistakes that get bugs closed without a fix

• Vague titles: "Button not working" tells a developer nothing
• Missing environment details: "it happens in my browser" is not reproducible
• No evidence: a screenshot or recording dramatically speeds up triage
• Missing starting state: reproduction steps that don't specify whether to be logged in, which account to use, or what data to set up
• Steps that skip assumptions: "add to cart" without specifying which product, in which quantity, with which options selected

For API bugs, include the request and response

For API-level bugs, include the full HTTP request (method, URL, headers, body) and the full response (status code, headers, body). Most developers can reproduce these in under a minute if they have this information.

Related reading: What is Exploratory Testing · Web Application QA Testing Checklist