How to Write a Good Bug Report That Developers Can Reproduce
A strong bug report reduces the time between discovery and resolution. It gives the team enough evidence to reproduce the problem, understand its impact and distinguish the defect from configuration, test-data or environment issues.
Confirm and isolate the problem
Reproduce the issue at least once when safe, then change one factor at a time: account, browser, device, data, network or environment. This helps identify whether the issue is consistent, intermittent or tied to a specific condition.
Check the latest requirement and known issues before reporting. Do not hide uncertainty—state the reproduction rate and any conditions you could not verify.
Practical checklist
- Reproduction rate
- Affected build and environment
- Account and test-data state
- Browser, device or API client
- Network and permission conditions
Write a precise summary
The title should describe the affected feature, action and visible failure. Avoid titles such as ‘Login issue’ or ‘Button not working.’ A useful title might be: ‘Checkout creates two orders when Confirm payment is selected twice.’
Keep the summary factual. Put investigation details and possible causes in the description unless the cause has been verified.
Provide reproducible numbered steps
Begin from a known state and include only the actions required to trigger the issue. Mention exact data when it matters, but never place real passwords, payment information or personal data in the report.
Separate the expected result from the actual result. This makes the broken rule explicit and prevents the reader from extracting the expectation from the steps.
Practical checklist
- Precondition
- Numbered actions
- Test data or safe identifiers
- Expected result
- Actual result
- Reproduction frequency
Attach useful evidence
Screenshots help with visual defects, while short recordings are useful for timing and multi-step behaviour. API bugs often need a sanitised request, response, status code and correlation ID. Logs should cover the relevant time window and remove credentials or personal information.
Evidence should support the report rather than replace the written reproduction steps.
Practical checklist
- Screenshot or short recording
- Timestamp and timezone
- Request and response for API issues
- Console or network error
- Sanitised logs and correlation ID
Assign severity based on impact
Severity describes technical or user impact; priority describes when the organisation intends to fix the issue. A cosmetic defect may become high priority before a launch, while a severe defect in an unused experimental feature may have lower immediate priority.
Explain the impact using affected users, blocked workflows, data risk, revenue or security instead of relying on a label alone.
Practical checklist
- Who is affected?
- Is a core flow blocked?
- Is there a workaround?
- Could data, money or privacy be affected?
- Is the issue a regression?
Key takeaways
- Reproduce and isolate the failure before reporting.
- Use a title that states feature, action and failure.
- Separate expected and actual results.
- Attach sanitised evidence with environment details.
- Explain impact when assigning severity.
Put it into practice
Open Bug Report Generator
Related practical guides
How to write test cases
Learn how to write clear, reviewable test cases with useful preconditions, numbered steps, test data and expected results.
Regression testing guide
Learn how to select, prioritise, maintain and automate a practical regression test suite without testing everything every time.
How to test an API
A practical API testing guide covering contracts, authentication, validation, permissions, state changes, errors and automation.