Beginner-Friendly Topic
Take your time - it's perfectly normal to re-read this topic 2-3 times. Try the interactive code editor below to run code yourself. Use the Q&A section to check your understanding before moving on. You've got this! 🚀
Bug Reporting Best Practices
A great bug report is more than a description of what went wrong - it is a complete, reproducible, professional document that enables a developer to find, understand, and fix the defect quickly. Poor bug reports waste developer time, get rejected as 'cannot reproduce', and create team friction. This is one of the most underrated skills in software testing.
Anatomy of a Great Bug Report
- Title: Precise, action-oriented, 1 line. Format: '[What] does [wrong] when [condition]'. E.g., 'Cart total shows incorrect value when promo code applied with international currency'.
- Environment: Browser version, OS, app version, environment (staging/prod), device. Critical for reproducibility.
- Severity & Priority: Technical impact (severity) and business urgency (priority).
- Preconditions: Exact setup required. Without this, developers waste hours trying to reproduce.
- Steps to Reproduce: Numbered, atomic, exact. If step 2 says 'click the button', specify WHICH button.
- Expected Result: What SHOULD happen according to specification or reasonable expectation.
- Actual Result: What ACTUALLY happened - exact error message, wrong value, screenshot.
- Attachments: Screenshots, screen recordings, browser console logs, network traces. A 10-second video saves 30 minutes of debugging.
- Reproducibility: Always/Sometimes/Rarely. Flaky bugs need frequency data.
Good vs Bad Bug Reports
// ❌ BAD BUG REPORT
// Title: "Login doesn't work"
// Description: "I tried to login and it failed. Please fix."
// Environment: My computer
// Steps: Tried logging in
// Expected: Should log in
// Actual: It didn't work
// Result: Developer cannot reproduce, marks as "Need More Info", bug sits for 2 weeks
// ══════════════════════════════════════════════════════════════
// ✅ GREAT BUG REPORT
// ══════════════════════════════════════════════════════════════
// BUG-0234
// Title: "Login fails with valid credentials on Safari 17 macOS Sonoma
// when 2FA is enabled - error: 'Session expired' on first attempt"
//
// Environment:
// Browser: Safari 17.2.1
// OS: macOS Sonoma 14.2.1
// App Version: v2.4.1 (build 461)
// Environment: Production
// Account type: Standard user with 2FA enabled
//
// Severity: Critical | Priority: High
// Reproducibility: 100% (always reproducible on Safari + 2FA accounts)
//
// Preconditions:
// 1. User account: qa.tester@company.com
// 2. 2FA enabled on the account (TOTP via Google Authenticator)
// 3. Previous session cleared (private browsing or cookies cleared)
//
// Steps to Reproduce:
// 1. Open Safari 17 in private mode
// 2. Navigate to: https://app.myproduct.com/login
// 3. Enter email: qa.tester@company.com
// 4. Enter password: [stored in QA password vault]
// 5. Click "Sign In"
// 6. When 2FA prompt appears, enter current 6-digit TOTP code
// 7. Click "Verify"
//
// Expected Result:
// User is redirected to /dashboard
// Session authenticated, dashboard loads within 2 seconds
//
// Actual Result:
// Error toast appears: "Session expired. Please log in again."
// User remains on the 2FA verification page
// Second attempt with a NEW TOTP code succeeds (intermittently)
//
// Console Error (F12 → Console):
// [Error] SameSite cookie issue: cookie "session_id" rejected
// because it has the "Secure" attribute but was not received
// over a secure connection.
//
// Network Tab:
// POST /auth/verify-2fa → 401 Unauthorized
// Response: { "error": "invalid_session", "code": "SESSION_EXPIRED" }
//
// Attachments:
// - screen-recording-safari-2fa-failure.mp4 [attached]
// - browser-console-log.txt [attached]
//
// Not reproducible on: Chrome 121, Firefox 122, Edge 121
//
// Workaround: None found. Affects all Safari users with 2FA (est. 18% of users)Common Mistakes
- Vague titles - 'Login broken' gets ignored; 'Login fails on Safari with 2FA enabled - Session expired error' gets immediate attention
- Missing environment details - 'works on my machine' is often an environment-specific bug; always include browser, OS, app version
- Not attaching screenshots or recordings - a 10-second screen recording is worth more than 10 paragraphs of description
- Writing the expected result as 'it should work' - specify exactly what behavior the specification promises
Tip
Tip
Practice Bug Reporting Best Practices in small, isolated examples before integrating into larger projects. Breaking concepts into small experiments builds genuine understanding faster than reading alone.
Technical diagram.
Practice Task
Note
Practice Task - (1) Write a working example of Bug Reporting Best Practices from scratch without looking at notes. (2) Modify it to handle an edge case (empty input, null value, or error state). (3) Share your solution in the Priygop community for feedback.
Quick Quiz
Common Mistake
Warning
A common mistake with Bug Reporting Best Practices is skipping edge case testing - empty inputs, null values, and unexpected data types. Always validate boundary conditions to write robust, production-ready software testing code.
Key Takeaways
- A great bug report is more than a description of what went wrong - it is a complete, reproducible, professional document that enables a developer to find, understand, and fix the defect quickly.
- Title: Precise, action-oriented, 1 line. Format: '[What] does [wrong] when [condition]'. E.g., 'Cart total shows incorrect value when promo code applied with international currency'.
- Environment: Browser version, OS, app version, environment (staging/prod), device. Critical for reproducibility.
- Severity & Priority: Technical impact (severity) and business urgency (priority).