Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 60 ยท Defects and Test Execution

Writing Excellent Bug Reports

Write bug reports developers can act on: clear title, exact steps, expected vs actual, environment, evidence, severity vs priority, reproducibility, plus a linter.

Finding a bug is only half of a tester's job; the other half is getting it fixed. A bug report is a message to someone who was not there when you saw the problem and who is probably busy with other things. If the report is vague, the developer will ask questions, wait for answers, fail to reproduce it, and close it as "cannot reproduce". If it is clear, the fix can start in minutes.

This lesson shows what a strong bug report contains, how to separate severity from priority, how to describe how often a problem happens, and what to avoid. The code is a stand-in: a small linter that checks a report for the problems reviewers complain about most. Real teams write reports in a tracker such as Jira (see the Jira and Agile tutorial), but the quality rules do not depend on the tool.

The parts of a good report

Anatomy of a bug report

Title One line with the symptom and place.
Steps Numbered, exact, repeatable.
Expected vs actual What should happen, what did.
Environment Build, browser, device, data.

Evidence and severity complete the picture.

1 / 2

Here is a complete report you could paste into any tracker.

TEXT
Title:        Coupon SAVE10 is applied twice when "Apply" is double-clicked
Build:        2.4.1-rc2, staging
Environment:  Chrome 126 on Windows 11, desktop layout, logged in as test user [email protected]
Steps:
  1. Add "Notebook (A5)" (price 8.00) to the cart. Cart total shows 8.00.
  2. Open the cart page.
  3. Type SAVE10 in the coupon field.
  4. Double-click "Apply".
Expected:     Coupon applied once: total is 7.20 (10% off).
Actual:       Total is 6.48 (10% off applied twice).
Reproduced:   5 out of 5 attempts. Single click works correctly (7.20).
Evidence:     Screenshot cart-double-discount.png, network log shows two POST /cart/coupon calls.
Severity:     Major (customers are charged the wrong amount).
Priority:     High (promotion starts Monday).
Requirement:  REQ-CART-07

Why it works: the title names the symptom and the trigger, the steps start from a known state, the numbers are checkable, and the last lines add the clue (a single click works) that probably points the developer straight at the cause.

Writing each part

Title. Summarize the problem so the report can be found and understood in a list. "Cart is broken" is useless. "Coupon SAVE10 is applied twice when Apply is double-clicked" can be searched, triaged and even recognized as a duplicate later.

Steps to reproduce. Number them, start from a clean, known state, and include the data you used. Remove steps that are not needed: the minimal set of steps is gold. Try the steps yourself on a fresh session before sending. If you cannot reproduce it, say so honestly (see below).

Expected versus actual. Always state both. Your expected result should come from a requirement, a design, a previous version or common sense; cite it if you can. A report that only says "the result is wrong" forces the developer to guess what "right" means.

Environment. Build or version, operating system, browser or device, language and region, user role, relevant configuration and data. Many bugs only occur in one environment; the information costs you ten seconds and saves a day of back-and-forth. Why environment parity matters is covered in Test Data and Test Environments.

Evidence. Screenshots (with the relevant part visible or marked), a short screen recording for timing or animation issues, logs, request and response bodies, and console errors. Never include real passwords, tokens or personal data in attachments.

One bug per report. If two problems appear in one report, one gets fixed and the other gets forgotten. If you are not sure whether two symptoms share a cause, file two reports and link them.

Severity versus priority

These two words are often confused, and the difference is important.

  • Severity is the technical impact of the defect: how badly it damages the system or the user's task. The tester usually proposes it.
  • Priority is the business urgency of fixing it: how soon, relative to other work. The product owner or team usually decides it.

They are independent, which is why all four combinations exist.

Low priority High priority
High severity Crash in a feature almost nobody uses, scheduled for removal Checkout crashes for all customers
Low severity Rare typo in an internal admin page Wrong company name in the home page headline before a launch

Typical severity scales are Critical, Major, Minor and Trivial, but the names and definitions differ between companies. Write the team's definitions down so people use the words the same way. You will use these ideas again when sorting defects in Defect Lifecycle and Quality Metrics and in Project: Run a Bug Triage Session.

Reproducibility

Say how often the problem occurs. "5 of 5 attempts" is valuable; "happens sometimes" is not. A few honest options:

  • Always: it happens every time with the listed steps.
  • Intermittent: it happens in some attempts. Give the rate (for example 3 of 10) and anything that seems to matter (timing, data, order).
  • Once: you saw it once and could not repeat it. Still report it with every detail you remember, and say clearly that you could not reproduce it. Do not invent steps.

Intermittent bugs are the hardest. Logs, timestamps, the exact build, and what you did just before are what developers need most.

Tone and common mistakes

  • Attack the problem, not the person. "The total is wrong" is better than "the developers broke the cart".
  • Do not guess the cause unless you label it a guess. Facts first, theory second.
  • Do not bundle several problems, or hide the key detail in a long story.
  • Do not leave out the expected result or your environment.
  • Do not reopen or argue in anger: if a bug is closed as "works as designed", ask where the design is documented, and suggest improving the requirement if it is unclear.
  • Check for duplicates before filing. Search the tracker with a few keywords.

Try it: a bug-report linter

This stand-in checks reports against a simple checklist: a specific title, numbered steps, both expected and actual results, an environment, a reproducibility statement, and a severity from the agreed list. It is a toy, but it shows how mechanical many review comments are. Try fixing the second report until it passes.

JS Lint bug reports

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The linter cannot tell whether your steps are correct, which is why the best check is still a quick reproduction by a colleague or by you in a fresh session.

Try it: severity and priority together

Triage is easier when severity and priority are explicit fields. This stand-in sorts a small backlog by priority first and severity second, which is how many teams order the fix queue, and shows that the two can disagree.

JS Order a fix queue

Press Run (or Ctrl + Enter) to see the console output here.

No output.

BUG-210 is the instructive one: a crash is severe, but if only a few people export huge reports and a workaround exists, the business may reasonably fix it later. Your job as a tester is to describe the facts so that the people choosing priority decide with good information.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which title is the best?

    A good title names the symptom and its trigger, so it can be found, understood and triaged without opening the report.
  2. 2. A typo in the company name appears in the home page headline the day before a launch. What is a sensible classification?

    The technical impact is small (a typo), but the business urgency is high because of visibility and timing.
  3. 3. You saw a failure once and cannot repeat it. What should you do?

    Be honest. Report the facts, evidence and context, and say it was seen once. Developers can use logs and timing even without steps.
  4. 4. Why should each bug report cover only one problem?

    One bug per report lets each be assigned, fixed, retested and tracked on its own.
  5. 5. Who usually decides priority?

    Testers propose severity (impact), while the business decides priority (urgency) after weighing other work.

Summary

  • A strong bug report has a specific title, minimal numbered steps, expected and actual results, environment, evidence, reproducibility, severity and priority.
  • Severity is technical impact; priority is business urgency; they are independent.
  • State how often it happens, and be honest about bugs you could not reproduce.
  • One bug per report, facts before theories, and a calm tone.
  • A checklist or linter catches the mechanical gaps; a second pair of eyes catches the rest.

Next: Defect Lifecycle and Quality Metrics.