How to Write a Bug Report: Template, Examples and Tips
A good bug report gets fixed fast. A vague one bounces between tester and developer for days. Learn the fields to include, copy a template and compare a bad report with a good one.
- A bug report must let a stranger reproduce the problem without asking you anything.
- Always include a specific title, numbered steps, expected result, actual result and the environment.
- File one bug per report, and attach a screenshot, video or log.
- Severity is the impact on the system, priority is how soon it should be fixed. They are different.
Finding a bug is half the job. The other half is making sure it gets fixed. Developers can only fix what they can see and repeat, so the quality of your report decides how fast that happens.
This guide shows how to write a bug report that is short, complete and hard to misunderstand. It fits naturally after you write cases with our guide on how to write test cases.
What a bug report is
A bug report, also called a defect report, is a structured description of a problem in software: what you did, what you expected, what really happened and where. It is the main communication between testers and developers, so clarity matters more than length.
The fields to include
| Field | What to write |
|---|---|
| Title | One specific sentence: what fails and where |
| Environment | App version or build, OS, browser or device, test or production |
| Steps to reproduce | Numbered actions, starting from a known state |
| Expected result | What should happen, based on the requirement |
| Actual result | What happened, including exact error text |
| Evidence | Screenshot, screen recording, console or server log |
| Severity and priority | Your assessment of impact and urgency |
| Frequency | Always, sometimes (e.g. 3 of 5 tries) or once |
A copy-paste bug report template
Title: [Area] What fails, under which condition
Environment: Build 2.4.1, Windows 11, Chrome 131, staging
Severity: High Priority: High Frequency: Always
Steps to reproduce:
1. Log in as a standard user
2. Add any item to the cart
3. Apply the coupon SAVE10
4. Click "Place order"
Expected: Order is created and the confirmation page opens
Actual: Spinner never stops; console shows 500 from /api/orders
Evidence: screenshot.png, console-log.txt
Notes: Works without a coupon. Not reproducible on build 2.4.0.A bad report vs a good report
Bad: “Checkout doesn’t work. Please fix urgently.”
This tells the developer nothing: which page, which user, what error, which build? They have to message you, wait for an answer, and try to guess. Now compare.
Good: “[Checkout] Order fails with HTTP 500 when coupon SAVE10 is applied.” Followed by the template above. The title alone tells the developer where to look, the steps let them reproduce it in a minute and the note “works without a coupon” narrows down the cause.
Tip: read your steps as if you were a new colleague. If any step needs knowledge that only you have, such as a test account or a hidden setting, write it down.
Severity vs priority
| Term | Meaning | Example |
|---|---|---|
| Severity | How badly the bug affects the product | Payments fail: critical |
| Priority | How soon the team should fix it | A typo in the company name on the home page: low severity, high priority |
Testers usually propose severity. Product owners or leads decide priority, because they know the business context and the release plan.
Habits that make reports better
- Reproduce it again before filing, ideally on a clean session, to rule out a one-off.
- Search for duplicates in the tracker before you create a new report.
- Find the narrowest steps. Remove anything that is not needed to trigger the bug.
- Record a short video when the problem involves timing, animation or many clicks.
- Stay neutral. Describe the behaviour, not the person who built it.
- Check API behaviour too. The status code in the network tab often saves time. Our HTTP status codes cheat sheet explains what each means.
Common mistakes
- Several bugs in one report. They cannot be fixed or closed independently.
- Missing expected result. Without it, the developer cannot tell whether your complaint is a bug or a feature request.
- No environment. A bug that only happens in one browser looks like “cannot reproduce” if you leave it out.
- Emotional language. “Terrible, totally broken” adds noise, not information.
- Never retesting. When the fix lands, verify it and add the build number to the report. A regression testing checklist helps you check that nothing else broke.
Final thoughts
Use the template every time, write the title last and test your steps once from scratch. A report that takes ten extra minutes to write usually saves hours of back and forth.
Frequently asked questions
What should a bug report contain?
A specific title, environment details, numbered steps to reproduce, the expected result, the actual result, evidence such as a screenshot or log, and severity and priority.
What is the difference between severity and priority?
Severity describes how serious the impact is on the product. Priority describes how soon the bug should be fixed. They often agree but not always.
How long should a bug report be?
As short as possible while still being reproducible. A title, five or fewer steps, and clear expected and actual results are usually enough.
Should I report a bug I cannot reproduce?
Yes, if it is serious, but say how often it happens, attach logs or a recording and note what you tried. Do not present it as always reproducible.
Which tool should I use to track bugs?
Any tracker your team already uses works, such as Jira, GitHub Issues, Linear or Azure DevOps. What matters is a consistent template and a clear workflow.
Keep learning
Need help with testing, WordPress or SEO?
We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.