How to write a good bug report (with a template and examples)

A good bug report is one a developer can fix without asking you a single question. A bad one starts a conversation: “Which page?”, “What were you doing?”, “I can’t reproduce it — what browser?” Each round trip costs both of you time, and some bugs never get fixed simply because nobody could work out what was reported.

The good news is that good bug reports follow a structure, and once you’ve used it a few times it becomes habit. This guide covers that structure, with examples and a template you can copy into your tracker.

The anatomy of a good bug report

Every useful bug report answers six questions:

What’s the problem? (title)
Where does it happen? (page and element)
How do I make it happen? (steps to reproduce)
What should happen, and what happens instead? (expected vs actual)
In what environment? (device, browser, screen size, account)
What evidence is there? (screenshot, recording, error message)

Plus one thing that helps the team plan: how bad is it? (severity or priority).

Let’s go through each.

1. Write a title that describes the bug, not your feelings

The title is what people scan in a list of fifty issues. It should say what’s wrong and where, in one line.

Weak title	Strong title
“Form broken!!!”	“Contact form: Submit button does nothing on iPhone Safari”
“Checkout issue”	“Checkout: discount code applied twice when page is refreshed”
“Header looks weird”	“Header: logo overlaps menu at tablet width (768px)”
“Bug on homepage”	“Homepage: ‘Pricing’ link goes to 404”

A good pattern: [Area]: [what goes wrong] [under which condition].

2. Say exactly where

Give the full URL of the page, not “the pricing page”. If the bug is about a specific element, describe it unambiguously — quote its text, or describe its position relative to something unique.

Better still, point at it. If your team reviews on the page itself, pin the report to the element so there’s no doubt about location. In ClientTweak, for example, a comment attaches to the element you click and can save a screenshot of what you were looking at along with your viewport size, so the developer opens the report and sees exactly what you saw.

3. Steps to reproduce

This is the most important part of the report, and the most often skipped. Write numbered steps starting from a known state — usually “go to this URL” — and include every click, input and choice.

Too vague:

“Tried to sign up and got an error.”

Reproducible:

Go to https://example.com/signup in a private browser window

Enter an email that’s already registered (e.g. test@example.com)

Enter any password and click Create account

Error appears: “Something went wrong” with no further detail

Tips:

Include the data you used. Test account names, the product you added to the basket, the text you typed.
Say how often it happens. Every time? One in five? Only the first time?
Mention what you ruled out. “Also happens in Chrome; doesn’t happen when logged out.”

If you can’t reproduce it yourself, say so — and still report what you saw. “Happened once, couldn’t repeat it” is useful information.

4. Expected vs actual

Spell out both, even when the expected behaviour seems obvious. What’s obvious to you might be a deliberate design decision to the developer, or vice versa.

Expected: A message saying “An account with this email already exists” with a link to log in.

Actual: A generic “Something went wrong” message. The form clears the password field.

This separation also helps when the “bug” turns out to be a misunderstanding of the requirements — it’s easy to see where expectations differ.

5. Environment details

Many bugs only happen in certain conditions. Record:

Device: e.g. MacBook Pro, iPhone 15, Samsung Galaxy tablet
Operating system and version: e.g. macOS 15, iOS 18, Android 14
Browser and version: e.g. Safari 18, Chrome 129 (find it in the browser’s “About” menu)
Screen or window size: especially for layout bugs
Account or role: logged in or out, admin or regular user, which test account
Environment: staging or production, and which URL

Some of this you’ll need to note yourself. Review tools vary in what they record automatically — some capture the window size, few capture everything — so add your browser and operating system to the report text whenever they might matter.

6. Evidence

A picture really is worth a thousand words in a bug report.

Screenshot with the problem visible (and circled, if it’s not obvious).
Screen recording for anything that involves motion, timing or several steps. A 20-second recording often replaces a paragraph of steps, and screen-recording tools like Loom make this quick.
Exact error messages, copied as text so they can be searched.
Console errors, if you’re comfortable opening the browser’s developer tools (right-click → Inspect → Console) — copy any red error lines.

7. Severity and priority

Teams use slightly different scales, but a simple three-level system covers most cases:

Level	Meaning	Example
High	Broken core functionality, data loss, security, blocks launch	Checkout fails; form submissions lost
Medium	Something works incorrectly but there’s a workaround	Filter resets when going back
Low	Cosmetic or minor	Icon slightly misaligned

Be honest with severity. If everything is “high”, nothing is.

The bug report template

Copy this into your tracker, review tool or a text snippet:

Title: [Area]: [what goes wrong] [condition]

Page: (full URL)
Element: (what on the page — or pin/screenshot it)

Steps to reproduce:
1. 
2. 
3. 

Expected: 
Actual: 
How often: Every time / Sometimes (x of y) / Once

Environment:
- Device / OS: 
- Browser + version: 
- Window size: 
- Logged in as: 
- Staging or production: 

Evidence: (screenshot, recording, error text)
Priority: High / Medium / Low

A complete example

Title: Booking form: date picker doesn’t open on iPhone Safari

Page: https://staging.example.com/book Element: “Choose a date” field in the booking form

Steps to reproduce:

Open the page on an iPhone in Safari

Scroll to the booking form

Tap the “Choose a date” field

Expected: A calendar opens so I can pick a date. Actual: Nothing happens. The keyboard doesn’t open either. I can’t complete a booking. How often: Every time (5/5)

Environment: iPhone 15, iOS 18, Safari. Logged out. Staging. Works in Chrome on the same phone and in Safari on a Mac.

Evidence: Screen recording attached. Priority: High — customers on iPhone can’t book.

A developer can pick this up and start fixing immediately.

Bug reports for different kinds of problems

The template works for everything, but different bugs need different emphasis.

Layout and visual bugs. The window size is the most important detail. Note the exact width if you can (most browsers’ developer tools show it), and whether resizing slightly makes the problem appear or disappear. Include a screenshot with the problem area marked.

Functional bugs. Steps to reproduce matter most. Include the exact data you entered, and whether the problem happens with other data too.

Intermittent bugs. Record the time it happened, how many attempts it took, and anything unusual — slow connection, multiple tabs, the page left open for a long time. The time helps developers find the right entries in server logs.

Content bugs. Quote the wrong text exactly and give the correct text. These are the fastest bugs to fix when reported well.

Performance problems. Note the page, your connection type (office Wi-Fi, mobile data), and roughly how long it took. “Slow” means different things to different people; “the product page took about 12 seconds to show images on mobile data” doesn’t.

Common mistakes

Several bugs in one report. Split them — each needs to be fixed, tested and closed separately.
Reporting the solution instead of the problem. “Add a loading spinner” might be right, but describe the problem first: “No feedback after clicking Pay; users click twice and are charged twice.”
Assuming the developer can see your screen. They can’t. Write for someone who has never seen what you saw.
Editing the report after the fix. Add new information as a reply, so the history stays clear.
Not re-testing. When a bug is marked fixed, check it, and close it or reopen it with what you see now.

Getting bug reports into the right place

The best bug report in the world is useless if it sits in an inbox. Agree with your team where reports go — your issue tracker, a review tool, or both — and keep them there. If QA reviews happen on the page itself but engineering lives in a tracker, connect the two so reports flow across automatically; ClientTweak can send comments to Jira, Asana, ClickUp or Trello, so findings land where developers already work.

Clear title, exact location, numbered steps, expected vs actual, environment, evidence, priority. Do that every time, and your bugs will get fixed faster — and fixed right.