How to Write a Defect Report That Does Not Start a Fight

Writing a defect report without blame: a tester and developer review one highlighted step together
In this post
  1. Why a defect report can read like an accusation
  2. What developers say they need
  3. Before and after: the same defect report
  4. How do you raise a risk with a PM or BA?
  5. When the developer still disagrees
  6. Sources

Take a tester on a checkout team who finds a broken discount code late on a Thursday. They log a defect report titled "Checkout totally broken again!!" in the bug tracker. The only other line reads: "I don't know how this got past code review." The developer tries the code once with a single item in the cart. It works, so they mark the report "cannot reproduce" and close it.

Both people may be acting in good faith, because the tester saw a real failure. The developer tested what the report gave them. But the report held a complaint and no facts, and the defect may sit in the build for another 2 days while they argue in the comments.

Why a defect report can read like an accusation

The ISTQB Foundation Level syllabus names this problem directly. ISTQB published the CTFL v4.0.1 syllabus in September 2024. Its section 1.5.1 says testers "are often the bearers of bad news." It adds that people tend to blame the person who brings bad news. Test results can feel like criticism of the product and of the person who built it.

The syllabus also points to confirmation bias, which is the habit of rejecting information that does not fit what you already believe. A developer who has just finished a feature may believe it works. A vague report makes it easy to keep believing that. For this reason, the syllabus asks testers to share defects and failures "in a constructive way". It also lists good communication and active listening as skills a tester needs to report and discuss defects. A constructive report is built from facts the developer can check for themselves.

What developers say they need

In 2010, Thomas Zimmermann and colleagues published What Makes a Good Bug Report? in IEEE Transactions on Software Engineering. They surveyed developers and reporters from the Apache, Eclipse and Mozilla projects and analysed 466 responses.

Developers rated steps to reproduce as the most important part of a report. Steps to reproduce are the exact actions someone takes to make the failure happen again. Stack traces came next, along with test cases. A stack trace is the error output that shows where in the code a failure happened. The biggest problems were errors in the steps and missing information. One developer wrote that absent information caused more delay than wrong information.

Another developer in the survey said that "rude or sarcastic bugs" do not help a reporter get their issue fixed. The authors also noted that reports with harsh tones were rated low by the reporters who scored them. The blaming report in our example left out the steps to reproduce. Its hostile wording may also make the developer less willing to dig in.

Before and after: the same defect report

Here is the report from the opening scenario, as the tester first logged it.

Before

  • Title: Checkout totally broken again!!
  • Description: Somebody broke the discount code AGAIN. I don't know how this got past code review. Please fix ASAP, this is blocking everything.

When you count what a developer can act on, the list is empty. There is no build number, no steps and no expected result. The words "again" and "somebody" suggest that a person is at fault. "Blocking everything" may not be true, and the developer can see that it might not be.

Section 5.5 of the syllabus lists what a defect report logged during dynamic testing typically includes. Here is the same failure, rewritten with those fields.

After

  • Title: Discount code SAVE10 not applied with 2 units of item 4471 in the cart.
  • Test object and environment: Checkout on staging, build 4.12.0-rc2, Chrome on Windows 11.
  • Context: Regression test case TC-118, run after the cart changes merged on Wednesday.
  • Steps to reproduce: Log in as test user qa_buyer_02. Add 2 units of item 4471 to the cart. Enter SAVE10 at checkout and select Apply.
  • Expected result: The total drops by 10%, from $40.00 to $36.00, as acceptance criterion 3 on story CART-212 states.
  • Actual result: The message "Code applied" appears, but the total stays at $40.00. With 1 unit in the cart, the discount applies correctly. A screenshot and the network log are attached.
  • Severity: High. Severity is how much the defect affects users or the business. Here, checkout says "Code applied" but still shows the full price. A customer could be overcharged.
  • Priority: Proposed high, for the product owner to confirm. Priority is how soon the team should fix it.
  • References: TC-118, CART-212.

Nothing in the second version names a person. It does not guess at the cause in the code either. The 1 unit and 2 unit results sit side by side, so the developer can see why their first check passed. The severity line explains the impact on the customer, which is harder to dismiss than an exclamation mark.

How do you raise a risk with a PM or BA?

Some problems you need to raise with a product manager (PM) or business analyst (BA) are not defects yet. Take the same team 2 days before release. The tester has not been able to test discounts on bundled products, because the test data for bundles does not exist. Nothing has failed. But nobody knows whether it works.

So what does the PM need to hear? How likely is a failure, and how much harm would it do? The product risk is that bundle discounts are worked out wrong. The missing test data is a project risk, a limit on the testing itself. Section 5.2.2 of the syllabus makes this split. Section 5.2.1 covers how to weigh a risk. Risk likelihood is how probable the problem is. Risk impact is the harm if it happens. Together they give the risk level. When you state both, the PM or BA can weigh the risk against the release date.

A message to the PM might read: "Discounts on bundles are untested, because we have no bundle test data. The cart code changed this week, so a failure is possible. If it fails, bundle buyers may pay the wrong amount. We can create the data and test tomorrow, or release and watch bundle orders closely. Which do you prefer?"

That message separates what is known from what is not. It names the impact in the PM's terms, which is money and customers. And it leaves the decision with the PM, who owns the release. Section 5.3.3 of the syllabus notes that different stakeholders want different information, so you tailor the message to the reader. A BA may want to know which acceptance criteria are untested. A developer may want the exact build and data.

If you are new to testing and want to practise writing a defect report someone can reproduce, Nopmark's First Software Testing course starts from the basics.

When the developer still disagrees

Sometimes the developer comes back and says it is not a defect. The syllabus allows for this. Section 5.5 says a reported anomaly may turn out to be a real defect or something else, such as a false-positive result or a change request. A false positive here is a test that reports a failure when the software is working as intended.

When that happens, treat the reply as information and ask what they saw when they followed your steps. If their result differs, compare builds, data and environments before anyone defends a position. If the requirement itself is unclear, take it to the BA or product owner. That way the team settles the question by checking the acceptance criteria.

The Google SRE book describes the same approach for production incidents (chapter 15, "Postmortem Culture," 2016). A blameless review focuses on the contributing causes without indicting any person or team. A defect report can work the same way. When every line is a fact the developer can check, the discussion stays on the software, and the defect can get fixed sooner.

Sources

Keep reading