Exit course
Chapter 5 of 9 Beginner 7 min read 2 quick checks Updated

Writing Bug Reports Developers Act On

On this page
  1. The template
  2. What each field is for
  3. A bad report and a good one
  4. Before you file
  5. Reporting from TestingBot Live

A bug you found but could not get fixed has the same value to users as a bug you never found. The bug report is the product of your testing, and its job is narrow: let a developer who was not there reproduce the problem on the first try, and let whoever triages it judge how much it matters.

The template#

Use the same fields every time. Most trackers (Jira, GitHub Issues, Linear, Azure DevOps and the rest) let you save this as an issue template.

TITLE        [Where] What goes wrong, under which condition
ENVIRONMENT  Build/version, URL or app version, browser + version,
             OS + version, device, account/role, test data
PRECONDITIONS State the system must be in before step 1
STEPS        Numbered, minimal, one action each
EXPECTED     What should happen (cite the requirement if there is one)
ACTUAL       What happens instead, word for word for messages
FREQUENCY    Always / 3 out of 5 attempts / once
EVIDENCE     Screenshot (annotated), video, console or device log, HAR
IMPACT       Who is affected and how badly; workaround if any
NOTES        What you already ruled out (other browsers, other accounts)

What each field is for#

  • Title. It will be read in a list of fifty others, so make it specific and searchable: where, what, when. "Checkout: order total ignores coupon when quantity is changed after applying it" beats "Coupon bug".
  • Environment. The difference between "it works on my machine" and a fix. Include the exact browser and OS versions, the build, and the account type. If it only happens on one environment, say which ones you tried that did not fail; that is often the most useful clue in the report.
  • Steps. The shortest path that still reproduces the bug. Before filing, try removing steps one at a time; if the bug still happens without step 3, step 3 does not belong in the report. Start from a known state ("Logged in as a customer with an empty cart"), not from "Open the app".
  • Expected and actual. State both, precisely. Copy error messages exactly, including codes. "Expected: total 45.00 (50.00 minus 10%). Actual: total 50.00; coupon line still shows -5.00."
  • Frequency. An intermittent bug is still a bug, but the developer needs to know not to give up after one attempt.
  • Evidence. A screenshot with the problem circled, a short video for anything involving motion or timing, and the browser console or device log around the time it happened. Logs often show the cause directly.
  • Impact. Separate severity (how bad the effect is: data loss, blocked purchase, cosmetic) from priority (how soon to fix it, which is usually the product owner's call). Give the facts that inform both: "Every customer who changes quantity after applying a coupon is overcharged" is impact. "URGENT!!!" is not.

You can reproduce a layout bug on Safari 18 for macOS. It does not happen on Chrome or Firefox on the same Mac. Where does that second fact belong?

"Safari only" points the developer straight at a WebKit rendering or CSS support difference and saves them from testing the other browsers themselves. What you ruled out is evidence too.

A bad report and a good one#

The same bug, reported twice.

Bad:

Title: Coupons broken

Coupons don't work in checkout. I tried a few times and the price was wrong. Please fix ASAP, customers will complain.

The developer has to ask which coupon, which product, which step, what "wrong" means, which browser, and whether it happens every time. The first answer arrives a day later and the tester no longer remembers the details.

Good:

Title: Checkout: coupon discount is dropped from the total when quantity is changed after applying it

Environment: staging, build 4.18.0. Chrome (latest) on Windows 11 and Safari 18 on macOS (both fail). Customer account, UK address.

Preconditions: Logged in as a customer, empty cart. Coupon SAVE10 (10% off, no minimum) is active.

Steps:

  1. Add "Desk lamp" (50.00) to the cart.
  2. In the cart, apply coupon SAVE10. Total shows 45.00.
  3. Change the quantity of "Desk lamp" from 1 to 2.

Expected: Total 90.00 (100.00 minus 10%), coupon line -10.00.

Actual: Total 100.00. The coupon line still shows -5.00, and the coupon stays listed as applied. Placing the order charges 100.00 (checked on order 10482).

Frequency: Always (5/5).

Evidence: annotated screenshot of the cart after step 3; console shows no errors; network log attached: the quantity update response contains "discount": 0.

Impact: Customers who change quantity after applying a coupon are charged full price while the page says the coupon is applied. Workaround: remove and re-apply the coupon.

Notes: Does not happen when quantity is changed before applying the coupon.

The good report took perhaps five more minutes to write. It saves the developer an hour, and the note about the network response probably tells them which line of code to look at.

Before you file#

Run through this quickly:

  1. Reproduce it again from a clean state, following your own steps literally.
  2. Search the tracker for an existing report; add your evidence there instead of filing a duplicate.
  3. Check one other environment if it is cheap: another browser, another account. "Only on Safari" and "everywhere" lead to very different fixes.
  4. Separate bugs. One report per problem, even if you found three on the same page.
  5. Keep the tone neutral. Describe what the software does, not what the developer did.

Your steps to reproduce have nine steps. Before filing, what should you do with them?

Minimal steps point at the cause: if the bug survives without step 3, step 3 is not part of the trigger. A video is good supporting evidence, but a developer cannot search, copy or follow a video the way they follow numbered steps.

Reporting from TestingBot Live#

When you find a bug in a TestingBot Live session (next chapter), the session toolbar has a Report Bug button. It takes a screenshot of the remote browser or device and opens an editor where you can annotate it. From there you can download the image, share it, or, if you have connected an issue tracker under Members > Integrations, create an issue directly; the Jira integration page shows the flow, and GitHub, Linear, Trello, Asana, Azure DevOps and Bugsnag are listed in the integrations docs. The annotated screenshot and the session metadata (browser or device, OS) are attached for you; the steps, expected and actual results are still yours to write.