How to write
a good bug report.
A practical guide for developers and QA, with an example and a template you can copy.
“The page is broken. Please fix it.” A developer cannot act on that: which page, broken how, on what browser, after what clicks? Each question costs a round trip, and some bugs never get fixed because nobody can reproduce them. Knowing how to write a good bug report removes most of that back-and-forth. The goal is simple: give the next person enough to see the same problem you saw.
What to include
What to include in a bug report.
Not every report needs every field. A typo on a marketing page does not need console logs. But a report that cannot be reproduced needs the first four items below.
-
A descriptive title
Say what happened and where. “Checkout total doesn’t update after removing a coupon” tells a developer what to look at. “Checkout bug” does not. Keep to one bug per report, so each can be assigned and fixed on its own.
-
Environment and preconditions
Browser and version (in Chrome,
chrome://version), operating system, app version or environment, and the account role you used. Add preconditions only if needed, such as being signed in or having an item in the cart. -
Steps to reproduce
Numbered steps, one action each, starting from a state the reader can reach. Use the names visible on screen, such as “click Apply coupon”. Write them even if the bug seems obvious, then run them once yourself.
-
Expected and actual result
What should have happened, and what happened instead. Quote error messages exactly, and describe what you saw, not what you think caused it or how to fix it.
-
Frequency and impact
Every time, or “3 of 5 attempts”? Who is affected and what can’t they do? Severity is how serious the problem is for users. Priority is how soon the team fixes it, and the team usually sets that.
-
Screenshots, recordings and logs
Attachments show what words cannot. Pick the kind that fits the problem, as explained in What to attach.
Bad vs good
The same bug, written twice.
This example is invented for illustration. It does not describe a real application.
Before Vague
Title: Checkout broken
Coupons don't work. Please fix.After Specific
Title: Checkout total doesn't update
after removing a coupon
Environment
- Chrome 130 on macOS 15, desktop
- Production, regular customer account
Preconditions
- Cart contains one item ($90.00)
Steps to reproduce
1. Open the cart and go to Checkout.
2. Enter coupon code SPRING10 and click
Apply coupon. The total changes to $81.00.
3. Click Remove coupon.
Expected result
The coupon is removed and the total returns
to $90.00.
Actual result
The total stays at $81.00. The coupon row
disappears, but the discount is still
applied. Reloading shows $90.00.
Frequency
Every time (5 of 5 attempts).
User impact
Customers may see a wrong total before
paying. Placing the order was not tested.
Attachments
- Screen recording (42 seconds)
- Console: TypeError: Cannot read properties
of undefined (reading "total")
- Network: DELETE /api/cart/coupon returned 500Why the second version is easier to investigate
-
01
The title can be found and triagedIt names the flow and the symptom.
-
02
The developer starts where you startedThe environment and precondition mean the same cart.
-
03
The steps can be checked as they goThe total changing to $81.00 lets the reader confirm they are on track.
-
04
The bug is a clear differenceExpected and actual results are separate, and “not tested” stops anyone assuming more.
What to attach
Screenshots, recordings and technical logs.
-
Screenshots
Best for what something looks like: wrong text, a misaligned layout, an error message. Show enough of the page to see where you are, and say what is wrong.
-
Screen recordings
Best for sequence and timing, such as a button that only fails after a certain click. Start near the first step, stop soon after the problem, and say what you expect and what you see.
-
Console and network logs
Open DevTools with
F12, choose Console for JavaScript errors or Network for failed requests (4xx and 5xx status codes), then repeat the steps. Chrome documents the Console and Network panels.
A clue, not a verdict
Pages log harmless warnings, and some failed requests are unrelated to your bug. Include only what appears when the problem happens, and let the developer judge the cause.
Template
A bug report you can copy and paste.
Paste this into your issue tracker or a document. Delete any section that does not apply.
Markdown Template
## Title
[What happens, and where. One issue only.]
## Environment
- Browser and version:
- Operating system / device:
- App version or environment (production, staging):
- Account type or role:
## Preconditions
[Only if needed: signed-in state, existing data, feature flags.]
## Steps to reproduce
1.
2.
3.
## Expected result
[What should happen.]
## Actual result
[What happens instead. Quote error messages exactly.]
## Frequency
[Every time / sometimes (e.g. 3 of 5) / once.]
## User impact
[Who is affected and what they cannot do.]
## Attachments
- Screenshot or recording:
- Console errors:
- Failed network requests (method, URL, status):
## Additional notes
[Workarounds, related reports, things you already ruled out.]Before you share
Remove credentials, access tokens, session cookies, personal information and anything else sensitive. Check recordings, screenshots, copied logs and request headers. If something cannot be removed, share it only through a channel that is appropriate for that data.
Using Show Along
How Show Along helps with browser bug reports.
Show Along is a Chrome extension for recording bugs. It gathers the attachments above in one recording, but it does not write the report for you: you still add the title, the expected and actual results, and the impact.
Show Along does not send recordings to the developer, and nothing goes online unless you connect Google Drive or OneDrive and choose to upload. It is not encrypted, so check a recording before you share it. See the privacy policy.
-
01
Screen recordingRecord the Chrome tab you choose and show the steps in order.
-
02
Microphone audioSay what you expect and what you see. The microphone is optional.
-
03
Console and network page detailsOff until you turn them on, then captured for the tab you are recording.
-
04
One timelineSteps, clicks, screenshots and page details line up with the video.
Quick answers
Good questions.
You do not need technical language. Say what you did, what you expected and what happened, in plain words, and add a screenshot or recording with your browser and the page address. Developers can work out the technical side if they can see what you saw.
Open DevTools with F12 (or Ctrl+Shift+J on Windows and Linux, Cmd+Option+J on macOS), choose the Console tab, repeat the steps, and copy the errors that appear when the bug happens, with the file they point to.
Passwords, access tokens, session cookies, API keys, personal details such as emails and phone numbers, and anything from other tabs that is not part of the bug.
Make it easy to reproduce.
A good bug report makes it easy for another person to understand, reproduce and investigate the problem.
Want to see it first? Read how Show Along works.