How to Write a Great Bug Report

A bug report is a message to the developer. Your job is to make the bug so clear that the developer can reproduce it and fix it without asking you questions.

1. The parts of a good bug report

1.1 Title (summary)

One short line that says what is wrong and where.

✅ Good: "Login page: error 500 when password contains the character &"
❌ Bad: "Login broken"

Tip: Use the format [Where]: [What happens] [When/How].

1.2 Steps to reproduce

A numbered list that anyone can follow, step by step. Start from the very beginning (for example: open the browser, go to the URL).

1. Open https://app.example.com/login
2. Enter email: test@example.com
3. Enter password: Pass&123
4. Click "Log in"

Rules: - Number every step. - One action per step. - Include the exact data you used (usernames, files, amounts).

1.3 Expected result

What should happen, based on requirements or common sense.

"User is logged in and redirected to the dashboard."

1.4 Actual result

What really happens.

"Error page with message '500 Internal Server Error' is shown. User is not logged in."

1.5 Environment

Where the bug happened:

Browser + version (e.g. Chrome 126)
Operating system (e.g. Windows 11, Android 14)
App version / build number
Test environment (staging, production)
Device (if mobile)

1.6 Severity and Priority

Severity = how bad the bug is (Critical / Major / Minor / Trivial).
Priority = how soon it should be fixed (High / Medium / Low).

See guides/testing-basics.md for more on this.

1.7 Attachments

Show, don't just tell:

Screenshot — for UI bugs. Mark the problem with an arrow or a box.
Screen recording — for bugs that need several steps.
Console / network logs — if you know how to get them (F12 in the browser).
Test data file — if the bug needs a specific file.

💡 A 30-second screen recording often saves 30 minutes of discussion.

2. Before you report — quick checklist

[ ] I reproduced the bug at least 2 times.
[ ] I checked if it was already reported (search the bug tracker).
[ ] I tested on the correct environment and build.
[ ] My steps are complete — a colleague could follow them.
[ ] I attached a screenshot or video.

3. Good vs Bad examples

❌ Bad bug report

Title: Checkout doesn't work Description: I tried to buy something and it failed. Please fix ASAP.

Why it's bad: No steps, no data, no environment, no evidence. The developer must guess everything.

✅ Good bug report

Title: Checkout: "Place order" button does nothing when cart has more than 20 items

Environment: Chrome 126 / Windows 11 / staging / build 2.4.1

Steps: 1. Log in as buyer@test.com (password: Test1234) 2. Add 21 different items to the cart 3. Go to cart → click "Checkout" 4. Fill in a valid address and click "Place order"

Expected: Order is created, confirmation page is shown. Actual: Nothing happens. Button shows spinner for 1 second, then stops. No error message. Console shows POST /api/orders 413 Payload Too Large.

Severity: Major | Priority: High Attachments: video.mp4, console-log.txt

Why it's good: Anyone can reproduce it. The console error even hints at the cause.

❌ vs ✅ Title comparison

❌ Bad	✅ Good
"Bug in search"	"Search: no results found for keywords with apostrophe (e.g. Levi's)"
"App crash"	"Android app: crash on startup after update to 3.2.0 on Samsung S23"
"Wrong price"	"Cart: total price shows $0 when discount code SAVE10 is applied"

4. Common mistakes junior testers make

Mixing many bugs in one report. One report = one bug. Always.
Writing opinions, not facts. Write "the button is grey and does not respond", not "the button is ugly and stupid".
Missing the build number. "Latest version" is not a version. Write the number.
Steps that start in the middle. Always start from a known state (e.g. "open the login page").
Reporting without reproducing. If it only happened once and you can't repeat it, write that clearly: "Seen once, could not reproduce yet."

5. Extra tips

Be polite. The developer is your teammate, not your enemy.
Retest after the fix. When the bug is fixed, test the fix AND the area around it.
If you are not sure it's a bug, ask first — "Is this the expected behavior?" is a normal question.

Next step: Use templates/bug-report-template.md — copy it for every new bug.