A bug report is a QA engineer’s most important communication tool. A poorly written bug report wastes hours — the developer cannot reproduce the issue, asks five follow-up questions, and the fix gets delayed by days. A well-written report gets fixed fast because the developer can reproduce the defect in minutes, understand the impact, and implement a targeted fix. The difference between a one-day resolution and a one-week resolution often comes down to the quality of the original report.
The Anatomy of a Great Bug Report
Every effective bug report contains the same core fields, regardless of which tracking tool you use. Each field eliminates a specific type of ambiguity that would otherwise slow down the fix.
# A well-structured bug report template
bug_report = {
"id": "BUG-1042",
"title": (
"Checkout fails with 500 error when applying discount code "
"containing special characters (%, &) on Chrome 120 / macOS"
),
"severity": "Critical",
"priority": "P1",
"module": "Checkout — Discount Code",
"environment": {
"browser": "Chrome 120.0.6099.129",
"os": "macOS Sonoma 14.2",
"url": "https://staging.shopeasy.com/checkout",
"build": "v2.3.1-rc2 (build #4587)",
},
"preconditions": [
"User is logged in with account test@shopeasy.com",
"Cart contains at least one item (e.g. 'Blue Sneakers', qty 1)",
"Discount code 'SPRING&SAVE' exists in the system (20% off)",
],
"steps_to_reproduce": [
"1. Navigate to /checkout",
"2. Verify cart summary shows the item and subtotal",
"3. Enter 'SPRING&SAVE' in the Discount Code field",
"4. Click 'Apply' button",
],
"expected_result": (
"Discount of 20% is applied. Subtotal updates to reflect the discount. "
"Success message 'Discount applied!' is shown."
),
"actual_result": (
"Page shows HTTP 500 Internal Server Error. "
"Console log: 'Unhandled exception in DiscountController.Apply — "
"System.FormatException: Input string was not in a correct format.' "
"No discount is applied. User must navigate back to /cart to retry."
),
"attachments": [
"screenshot_500_error.png",
"console_log_discount_error.txt",
"network_har_capture.har",
],
"additional_notes": (
"Tested with discount codes without special characters (e.g. 'SAVE20') — "
"those work correctly. The issue appears specific to codes containing "
"& or % characters. Reproducible 100% of the time."
),
}
print(f"{'='*60}")
print(f" BUG REPORT: {bug_report['id']}")
print(f"{'='*60}")
print(f" Title: {bug_report['title']}")
print(f" Severity: {bug_report['severity']}")
print(f" Priority: {bug_report['priority']}")
print(f" Module: {bug_report['module']}")
print(f"\n Environment:")
for key, val in bug_report['environment'].items():
print(f" {key}: {val}")
print(f"\n Steps to Reproduce:")
for step in bug_report['steps_to_reproduce']:
print(f" {step}")
print(f"\n Expected: {bug_report['expected_result']}")
print(f"\n Actual: {bug_report['actual_result']}")
print(f"\n Attachments: {', '.join(bug_report['attachments'])}")
Common Mistakes
Mistake 1 — Omitting environment details
❌ Wrong: “The checkout page crashes.” (No browser, OS, build version, or URL)
✅ Correct: “The checkout page returns HTTP 500 on Chrome 120 / macOS Sonoma when applying discount code ‘SPRING&SAVE’ on staging build v2.3.1-rc2.”
Mistake 2 — Writing “could not reproduce” without enough attempts
❌ Wrong: Trying the steps once, not seeing the issue, and closing the report as “Not Reproducible.”
✅ Correct: Trying at least three times across different browsers and environments, checking if the issue is timing-dependent or data-dependent, and documenting all attempts before marking it as not reproducible.