Bug Reporting Guide

How to write clear, actionable bug reports that developers can reproduce and fix quickly.

Why good bug reports matter

A bug report is a handoff document. The clearer it is, the fewer cycles a developer spends decoding it and the faster the fix ships.

The real cost of a bad report is not the extra writing time; it is the round trips of "I cannot reproduce" that burn both sides of the team. Aim for a report so complete that reproduction never requires the original tester.

Required fields

Every report needs the minimum data a developer cannot guess. Fill all of it before submitting a single issue.

Title — concise summary of the bug and its impact.
Steps to reproduce — numbered, exact actions from a known starting state.
Expected result — what should have happened.
Actual result — what actually happened.
Environment — browser, OS, device, app version, network conditions.
Severity and priority — impact on users and urgency for release.

Writing a great bug title

Lead with the component, the action and the symptom: "Checkout fails with 500 after entering an expired promo code." This one line tells a developer where to look and what broke.

Avoid titles that only describe the area, such as "Checkout problem" or "Login broken." If the reader cannot picture the failure from the title alone, rewrite it.

Making steps reproducible

Reproducible steps are minimal and deterministic. Start from a clean state, name the exact data used, and number the actions.

Remove anything that does not matter. If the bug appears with one product in the cart, do not begin with three signup forms and a profile edit. Fewer steps means faster debugging and a clearer root cause.

Including evidence

Screenshots show what the user saw; logs and network responses show why. Capture the console, network and application logs whenever a bug relates to an error state.

For flaky or UI bugs, record a short screen capture. Annotate screenshots to point at the failing region, and never paste passwords or session tokens into evidence.

Severity vs priority

Severity describes impact: how badly users are affected. Priority describes urgency: how soon it must be fixed relative to a release.

A cosmetic typo on the homepage is low severity but possibly high priority because executives and customers see it. A rarely hit data corruption bug is high severity but lower priority in a single release. Teams decide priority, so state severity clearly and let planning handle the rest.

Common reporting mistakes

The most common failures are missing environment, steps that skip a hidden precondition, expected results that say "it should work," and one report bundling several unrelated bugs.

Report one issue per ticket. A bundled ticket gets fixed partially, closed early or lost entirely, and it makes triage and release notes unpredictable. Also check for duplicates before filing.

Template outline

A reliable skeleton saves time on every ticket. Fill in: description of the bug, environment details, numbered reproduction steps, expected result, actual result, severity, priority, and evidence.

Add a "worked previously in version" line where useful. When a bug is a regression, that single detail can lead a developer straight to the change that caused it.

Related tools: Rebuild suspect requests with the API Response Viewer and pretty-print API payloads with the JSON Formatter. Pair with SQL for Testers to verify data states.