Software Testing

Beginner path · lesson 22 of 35

BeginnerFundamentals4 min readPublished November 12, 2026

What is a bug report? How to write a great one

A bug report is how a problem you found becomes a problem someone fixes. Here's what to put in it, a template you can reuse and the habits that get bugs fixed faster.

On this page

Key takeaways

  • A bug report describes a problem so clearly that someone else can reproduce it, understand its impact and fix it.
  • The core is simple: steps to reproduce, expected result, actual result, plus the environment and evidence.
  • Great reports are specific, minimal and neutral. One bug per report, facts not blame.

What a bug report is

A bug report (also called a defect report or issue) records a problem you found. It's usually written in a tracking tool like Jira, Azure DevOps, GitHub Issues or Bugzilla.

It has three readers:

  • The developer, who needs to reproduce it and find the cause.
  • The product owner or lead, who decides how urgently to fix it.
  • Future you, who needs to retest it once it's fixed.

A bug that can't be reproduced usually can't be fixed. That makes the report as important as the finding.

What goes into a bug report

FieldWhat to write
TitleWhat's wrong, where, under what condition. Short and specific.
EnvironmentApp version or build, browser or device, operating system, test environment, user role.
PreconditionsAnything needed before the steps: account type, data, settings.
Steps to reproduceNumbered, minimal, exact. Include the data you used.
Expected resultWhat should happen, ideally with a link to the requirement.
Actual resultWhat actually happened. Exact error messages, copied, not paraphrased.
FrequencyEvery time, or 3 of 10 attempts?
SeverityHow serious the impact is. Priority is often set later by the product owner.
AttachmentsScreenshot, video, logs, network requests (HAR file), console errors.

A weak report and a great one

Real-world exampleThe same bug, reported twice

Weak:

Title: Checkout broken!!!

Checkout doesn't work. Please fix ASAP.

The developer has to guess everything: which page, which user, which payment method, what "doesn't work" means.

Great:

Title: Checkout: "Pay" button does nothing when a discount code is applied (Safari 17)

Environment: Build 2.14.0, staging, Safari 17.4 on macOS 14. Logged-in customer.

Steps:

  1. Add any product to the cart.
  2. Apply discount code SPRING10.
  3. Go to checkout and click Pay.

Expected: The payment form opens.

Actual: Nothing happens. The console shows TypeError: discount.total is undefined.

Frequency: 5 of 5 attempts. Works in Chrome 124. Works in Safari without a discount code.

Attachments: screen recording, console screenshot.

Lesson: the second report already narrows the problem down to Safari plus a discount code, before a developer even opens it. That's what isolating a bug means, and it saves hours.

Habits that get bugs fixed

  1. Reproduce it first. Try again before reporting. Note whether it happens every time.
  2. Isolate it. Change one thing at a time: another browser, another user, other data. Each difference you find narrows the cause.
  3. Search for duplicates. Someone may have reported it already. Add your details there instead.
  4. One bug per report. Two problems in one report means one gets forgotten when the other is fixed.
  5. Minimal steps. Remove every step that isn't needed to trigger the bug.
  6. Copy, don't paraphrase. Exact error text, exact values, exact URLs.
  7. Stay neutral. Describe the product's behaviour, not the person who built it.

Do

Write titles like a search query: "Invoice PDF: VAT shows 0 for orders with free shipping." Anyone can find it later.

Don't

Write titles like "Bug in invoices", "Doesn't work" or "URGENT!!!". They hide the problem and set the wrong tone.

After you report it

A bug report has a life cycle. Common states are New → Assigned → Fixed → Retest → Closed, with Reopened if the fix doesn't work.

When a fix arrives, run your original steps again to confirm it's gone. Then check the area around it, in case the fix broke something else.

Check yourself

You found that the search page shows no results for the word 'café', but works for 'cafe'. What's a good bug report title?

Show answer

Something like: "Search: no results for queries with accented characters (e.g. 'café'); 'cafe' works." It says where the bug is, what triggers it and gives an example, so anyone can understand the bug from the title alone.