How to Write a Defect Report
A bad bug report wastes days. A good one gets fixed in hours. Learn the anatomy of a report that developers actually want to read.
1 The Hook — Why This Matters
A tester on an Auckland e-commerce team logged a bug with the title “It doesn't work” and no description. The developer spent three days asking follow-up questions, reproducing wrong scenarios, and guessing at the actual problem. By the time the real issue was understood, the sprint had ended and the fix was pushed to the next release.
The same bug, reported properly, was reproduced in ten minutes and fixed in two hours. The difference was not the bug. The difference was the report.
Developers are not mind readers. A defect report is a transfer of information from the person who found the problem to the person who will fix it. If that transfer is noisy, incomplete, or emotional, the fix takes longer and the product suffers. Writing good reports is a skill you can learn today.
2 The Rule — The One-Sentence Version
A good defect report gives a stranger everything they need to reproduce the bug, understand its impact, and prioritise it correctly — in under two minutes of reading.
That stranger might be a developer in Christchurch, a test lead in Wellington, or a product owner reviewing the backlog six months from now. The report must stand alone.
3 The Analogy — Think Of It Like...
A police incident report.
When a constable in Christchurch files a report, it must be precise enough that another officer could pick up the case tomorrow, understand what happened, where it happened, who was involved, and what evidence exists. Vague reports get buried. Precise reports lead to arrests. A defect report is the same: it must be complete enough that another team member could reproduce the bug without talking to you. If they have to message you on Slack to ask what you meant, the report has failed.
4 Watch Me Do It — Bad vs Good
Here is the same bug reported two ways. The scenario: an Abel Tasman kayak hire booking system in Nelson. A customer selects a date, enters their details, clicks “Book Now,” and the page refreshes with no confirmation and no error.
Summary: Booking broken
Description: I tried to book a kayak and it didn't work. This is really frustrating and needs to be fixed ASAP.
Steps: None provided
Expected: Should work
Actual: Broken
Summary: Kayak booking form silently fails on Safari 17 when date is selected via calendar picker
Description: On the Abel Tasman kayak hire booking page, selecting a date via the calendar picker and clicking “Book Now” causes a silent failure. The page refreshes with no confirmation, no error message, and no booking recorded in the admin panel. This occurs only in Safari; Chrome and Firefox behave correctly.
Steps to Reproduce:
- Navigate to https://kayak.example.co.nz/book
- Select any future date using the calendar picker (not manual typing)
- Enter valid name, email, and phone number
- Click “Book Now”
Expected Result: Booking confirmation page displays with reference number and confirmation email sent.
Actual Result: Page refreshes to the booking form. No confirmation. No email. Admin panel shows no new booking.
Environment: Safari 17.1, macOS Sonoma 14.2, 1920×1080. Reproduced on iPhone 15 Pro (iOS 17.1). Does NOT reproduce in Chrome 120 or Firefox 121.
Severity: High — core booking flow broken for Safari users (~18% of NZ traffic)
Priority: High — affects revenue during peak summer season
Attachments: safari-booking-fail.mp4 (screen recording), safari-console-log.txt (JavaScript errors)
5 When to Write a Formal Report / When NOT To
✅ Write a formal defect report when...
- The bug affects a production or staging environment
- The fix requires developer code changes
- You need traceability for audit or compliance
- The bug might regress and needs a permanent record
- Multiple people could encounter it (not just your machine)
❌ A quick message is enough when...
- The “bug” is a typo or cosmetic issue you can fix yourself
- You are pair-testing with the developer at the next desk
- The environment is a local dev build and the fix is already in progress
- A Slack message with a screenshot is faster and the team agrees
- It is a test data issue that you can reset in two minutes
Before you submit a defect report, ask:
- Do you have the reproduction steps? Can the developer follow them without your help?
- Have you included the environment details (OS, browser, version)?
- Is your title specific enough that it appears sensible in a backlog?
6 Common Mistakes — Don't Do This
🚫 Vague titles like “It doesn't work”
I used to think: The developer will read the description anyway, so the title doesn't matter much.
Actually: Titles appear in sprint boards, email notifications, and backlog summaries. A vague title forces every stakeholder to open the ticket to understand it. A precise title (“Checkout button unresponsive on mobile Safari after login”) lets the team triage in seconds without opening the description.
🚫 No reproduction steps or missing environment details
I used to think: The developer knows the system well enough to figure it out.
Actually: A bug that reproduces on Chrome 120 on Windows might not reproduce on Chrome 120 on macOS. A bug at 1920×1080 might vanish at mobile width. Always list browser, OS, viewport size, and account details. If you don't know, say “Unknown — needs verification.”
🚫 Emotional language and severity based on annoyance
I used to think: If a bug annoyed me, it should be marked Critical.
Actually: Severity measures impact on the business and users, not your personal frustration. A misspelled company name on the homepage is embarrassing but does not block functionality. A broken password reset flow blocks every new user. Severity should be objective: Critical = system down or data loss, High = major feature broken, Medium = workaround exists, Low = cosmetic. Let the product owner set Priority; you provide the facts.
When defect reports fail
The most common failure is submitting a report so vague that the developer cannot reproduce it. Without reproduction steps, the report sits in the backlog untouched until you become unavailable—then nobody else can finish the investigation. A defect report is only useful if another tester (or a developer on another team) can pick it up and act on it immediately.
7 Now You Try — Rewrite This Report
Scenario: A Wellington-based food delivery app has a bug. Rewrite the bad report below into a proper defect report with all required fields.
Title: App is broken
Description: I was trying to order lunch and the thing crashed. This is the third time this week. Fix it please.
Steps: Open app, try to order
Expected: Order goes through
Actual: Crash
Task: Write a proper Summary, Description, Steps to Reproduce, Expected Result, Actual Result, Environment, Severity, and Priority. Then click reveal to compare with a model answer.
Summary: App crashes on payment screen when applying promo code on iOS 17
Description: On the Wellington Eats iOS app, navigating to the payment screen and applying any promo code causes an immediate crash to the home screen. The crash is 100% reproducible with valid and expired promo codes. The user loses their cart contents and must re-add items.
Steps to Reproduce:
- Open Wellington Eats app v3.4.1 on iOS 17.2
- Add any item to cart from a restaurant in the CBD
- Tap “Checkout”
- On the payment screen, tap “Add Promo Code”
- Enter “LUNCH20” and tap “Apply”
Expected Result: Promo code is validated and discount applied to order total.
Actual Result: App crashes to iOS home screen. Cart is lost.
Environment: iPhone 14 Pro, iOS 17.2, Wellington Eats v3.4.1. Wi-Fi and 5G tested. Does NOT reproduce on Android 14.
Severity: High — core checkout flow blocked for iOS users
Priority: High — affects revenue during lunch peak hours
How did you do? If your answer included specific steps, environment details, and objective severity, you are writing reports that developers will thank you for.
🎯 Want hands-on practice with AI feedback?
Try the Bug Report Writing Worksheet — analyse a planted bug, fill in the full report template, get instant AI critique, and compare with a model answer.
8 Self-Check — Can You Actually Do This?
Click each question to reveal the answer. If you got all three, you are ready to file real defects.
Q1. What are the eight essential fields of a good defect report?
Summary, Description, Steps to Reproduce, Expected Result, Actual Result, Environment, Severity, Priority, and Attachments (screenshots or logs). Some teams add Assignee, Component, or Sprint, but those eight are the foundation. Omit any one and the report becomes harder to act on.
Q2. Why should severity and priority be kept separate?
Severity is an objective measure of technical impact: how badly is the system broken? Priority is a business decision: how soon should it be fixed? A typo on the CEO's keynote slide is low severity but high priority. A rare edge-case memory leak is high severity but low priority if it only affects 0.01% of users and has a workaround. Testers recommend severity; product owners set priority.
Q3. A developer says they cannot reproduce your bug. What is the most likely cause, and what should you add to the report?
The most likely cause is missing environment detail or incomplete steps. Add the exact browser version and operating system, the specific test account and data used, the viewport size, whether cookies were cleared, and any network conditions (VPN, corporate proxy, mobile data). A screen recording is often the fastest way to close the reproduction gap. Never take “cannot reproduce” personally; treat it as a signal that the report needs more precision.
9 Interview Prep — Junior Q&A
Defect reporting is a core junior tester skill. Employers ask these questions to see if you understand quality communication.
Q. "What makes a good bug report?"
A good bug report has a clear, specific title, precise reproduction steps, environment details (OS, browser, version), and expected vs. actual behaviour. It avoids emotional language and focuses on facts. The developer should be able to follow the steps and reproduce the bug without asking for clarification. A good report also includes attachments (screenshots, logs) if they help.
Q. "You discover a bug that can only reproduce on your machine. What do you do?"
I would still write a formal defect report, but I'd be transparent about the limitation. I'd note: "Reproduced on: Windows 11, Chrome 120, NZ locale, with test account XYZ. Could not reproduce on macOS. Environment details: 1920×1080 viewport." Then I'd ask for help from the team—maybe another tester can reproduce on Windows, or a developer can inspect the code for browser-specific issues. Transparency is better than silence.
Q. "How would you decide between marking a bug Critical vs. Medium?"
Critical means users cannot work at all or data is lost. A checkout button that doesn't work is Critical. Medium means there's a workaround or a non-essential feature is broken. A misspelled label is Low. I would focus on user impact and business consequence, not on how annoying the bug is to me personally. The product owner sets Priority; I provide severity facts.