How to Write a Bug Report

What a good bug report contains

• Title — the symptom in one specific line: "Checkout returns 500 when the cart contains a discounted item" beats "Checkout broken".
• Environment — app version or build, browser/OS or device, API environment (staging, production), account or role used.
• Preconditions — what must be true before the steps: a logged-in user with items in the cart, a specific feature flag.
• Steps to reproduce — numbered, minimal, exact. Include the data you used (or a generated equivalent) and the request if it is an API bug.
• Expected result — what should have happened, ideally with a reference to the requirement or design.
• Actual result — what happened instead, quoted exactly: the message, the status code, the wrong value.
• Evidence — screenshot or recording, the HTTP request and response, console or server log lines, a stack trace.
• Frequency — always, intermittent (how often), only on first load.
• Severity and priority — how bad it is and how soon it must be fixed (see below).

Try it: AI Bug Description Generator Try it: AI Bug Title Generator

A bug report template

Title:        Checkout returns 500 when the cart contains a discounted item
Environment:  Web app 4.12.0 · Chrome 128 / Windows 11 · staging · customer role
Severity:     Major        Priority: High        Frequency: Always

Preconditions:
  - Logged in as a verified customer
  - Cart contains one item with an active 20% discount (SKU A-100)

Steps to reproduce:
  1. Open /checkout
  2. Select "Card" as the payment method
  3. Click "Place order"

Expected result:
  Order is created (201), confirmation page shows the discounted total 199.20

Actual result:
  Page shows "Something went wrong". POST /api/v1/orders returns 500:
  {"error":{"code":"INTERNAL","requestId":"9f1c…"}}

Evidence:
  - screenshot-checkout-500.png
  - request/response captured (attached)
  - server log: TypeError: cannot read "rate" of undefined (discount.ts:41)

Notes:
  Works when the cart has no discounted item. Started after release 4.12.0.

Try it: AI Bug Description Generator Try it: HTTP Request Inspector

Severity vs priority

Severity measures impact on the system or the user: how much is broken and for whom. Priority measures urgency to the business: how soon it must be fixed relative to other work. They are set by different people and often disagree.

A typo in the company name on the login page is trivial severity but high priority. A crash in an admin report that runs once a quarter is high severity but low priority until the quarter ends. Recording both, separately, is what lets a team plan honestly.

• Severity — Blocker (no workaround, core flow unusable), Critical (data loss, security, payment failure), Major (feature broken, workaround exists), Minor (cosmetic or edge case), Trivial.
• Priority — Highest / High (fix before release or now), Medium (next sprint), Low (backlog).

Try it: AI Bug Severity Suggestion Try it: AI Bug Priority Suggestion

Before you file: isolate the bug

• Reproduce it twice. If it happens once, note it as intermittent and record what differed.
• Reduce the steps to the minimum that still triggers it. Remove anything that does not change the outcome.
• Change one variable at a time — different browser, different account, different data — to find the trigger.
• Check whether it is already reported: search the tracker for the error message and the endpoint.
• Capture the evidence while it is on screen: the request, the response, the console, the exact message.

Try it: AI Error Message Analyzer Try it: API Response Analyzer

Mistakes that get reports bounced

• No steps, only a description of the symptom.
• "Does not work" as the actual result, with no message, code or screenshot.
• Several bugs in one report — each needs its own lifecycle.
• Opinion in the title ("this is terrible") instead of the symptom.
• Real customer data pasted into the report. Use generated test data that reproduces the same shape.
• Missing environment — a bug that only appears on Safari on iOS wastes a day if that is not stated.

Try it: Test Data Factory

Reporting API bugs

For an API defect the reproduction is the request. Include the method, URL, headers (with tokens redacted), body, and the full response — status, headers and body — plus the request id if the API returns one. A cURL command is the most portable form: a developer can paste it and see the failure immediately.

Try it: HTTP Request Inspector Try it: cURL Generator

Frequently asked questions