Bug report template: how to write a bug report, with examples

A bug report has one job: to get the bug from the person who saw it to the person who can fix it, with nothing lost on the way. When a report is vague, the developer either guesses, asks, or closes it as “could not reproduce”. All three cost more time than writing it properly would have.

What a bug report contains

Each field below answers a question the developer would otherwise have to ask.

• Title. What is wrong, when, and where, in one line. “Pay button does nothing after a declined card, on Android” can be sorted, searched and recognised in a list. “Checkout bug” cannot.
• Where. The page or screen, named the way the app names it. A developer can then go straight to the right part of the code.
• Platform, device, browser and app version. Many bugs only happen on one platform, one browser or one build. Without the version, nobody can tell whether the bug is already fixed in a newer one.
• Steps to reproduce. Numbered, one action each, starting from somewhere anyone can reach. Include the account and the data you used. This is the most important part of the report: a bug a developer can repeat is usually a bug they can fix.
• Expected result. What should have happened. Without it, the developer has to guess whether you found a bug or a design decision you disagree with.
• Actual result. What happened instead. Copy error messages word for word. “An error” is not enough; the exact message often points to the exact line.
• How often. Every time, sometimes, or once. A bug that happens every time is found quickly. One that happens 1 in 10 times needs that number, or the developer will try twice, see nothing, and stop.
• Severity and priority. Severity is how bad the bug is for the person who meets it. Priority is how soon it should be fixed. They usually agree, but not always: a spelling mistake on the home page is minor and urgent. Add one line saying why.
• Attachments. A screenshot shows the wrong state. A screen recording shows how you got there, which often reveals a step you forgot to write down. Keep anything private out of the frame.
• Reporter and time. Who to ask, and when it happened. The time lets a developer find the matching lines in the server logs.

The template

Copy it into your tracker, an email or a chat message. Delete what does not apply, but keep the steps, expected and actual results in every report.

# Bug report

**Title:** [What is wrong] when [what you did], on [where]
**Where:** [Page or screen, e.g. Checkout > Payment]
**Platform:** [Web / Android / iOS]
**Device and version:** [e.g. Pixel 7, Android 14 / Chrome 129 on macOS 15]
**App version or build:** [e.g. 2.4.1 (212), or the staging URL]
**Account used:** [Which test account, and anything special about it]

## Steps to reproduce
1. [Start from somewhere anyone can reach]
2. [One action per step]
3. [The step where it goes wrong]

## Expected result
[What should have happened, concretely]

## Actual result
[What happened instead, with the exact wording of any message]

## How often
[Every time / 3 out of 5 tries / once, could not repeat]

## Severity
[Blocker / Major / Minor / Cosmetic]: [one line on why]

## Attachments
- [Screenshot of the wrong state]
- [Screen recording of the steps]

**Reported by:** [Name]
**When:** [Date and time, with time zone]

Bug report examples: weak and strong

The same two bugs, written up twice: first as a one-line message, then with every field filled in.

In both cases the strong report narrows the bug down before anyone opens the code. The checkout report says it only happens after a decline, and only on Android. The login report says it only happens with a space in the password. That narrowing is most of the work of fixing a bug, and the tester is often best placed to do it.

Common mistakes

• Several bugs in one report. One will be fixed and the report closed, and the others are lost. File one report per bug.
• Steps that start in the middle. “Tap Pay” is not a starting point. Start from opening the app or a page anyone can reach.
• A diagnosis instead of a description. “The API is timing out” is a guess. Describe what you saw, and add the guess separately if it helps.
• No version or device. The developer tests on their own setup, it works, and the report is closed.
• Paraphrased error messages. Copy the exact text, or take a screenshot of it.
• Everything marked critical. When every bug is urgent, none of them are. Keep the top severity for bugs that block a customer or lose data.
• Not checking for duplicates. Search before filing. If the bug is already reported, add your device or steps to the existing report.

What happens after the report

A well written report still fails if it sits somewhere the developer does not look. The report should reach them where they already work, usually their issue tracker, with a link back to where it was found.

The loop is not closed when the developer says it is fixed. The person who reported the bug should be told, and asked to check it again on the same platform and, ideally, the same device. That retest is what confirms the fix. The guide to retesting and regression testing explains how to run it, and what else to check around the fix.

How qarunbook handles bug reports

• Every bug raised in qarunbook gets a short code, like QA-13, on the check that found it.
• Screenshots and screen recordings can be attached to the issue.
• With GitHub connected, each new issue can be filed in the repository automatically, with its code in the title. The GitHub issue template guide covers the format.
• A pull request that says Fixes QA-13 marks the issue fixed when it merges.
• The tester who raised it is then told to check it again.

Testing, simplified and effective. Create a free account to try it.