How to write a bug report
A tester writes that checkout is broken. The developer opens the report and still has to ask which account, which item, which build and what should have happened. The report contains urgency but not a path back to the observation.
Learning how to write a bug report means preserving the smallest useful story: where the behaviour begins, what action changes the state, what was observed, what was expected and which evidence another person can verify.
How to write a bug report from the smallest useful path
Begin with a short title that names the object, condition and visible failure. Then remove steps until the defect still appears. A small path helps the reader test the claim without navigating through unrelated setup.
If the issue requires a special account, data or feature flag, name it in the environment or preconditions. Do not bury the only reproduction key in a screenshot.
Separate expected behaviour from the observation
Write what the product should do based on a requirement, agreement or clearly stated user action. Then write what actually happened. The difference is the defect story. Avoid replacing both with a verdict such as wrong or does not work.
When the requirement is uncertain, label the report as a question or include the missing decision. A report should not turn an assumption into a fact.
Add context that changes the result
- Build, environment and relevant browser or device.
- Account role, data state and feature flags.
- Frequency or conditions under which the issue appears.
- Network, console or API evidence when it narrows the cause.
Include only context that can affect reproduction or prioritisation. A long environment essay makes the important difference harder to see.
Choose evidence that another person can use
A screenshot can show the final state, but it rarely explains the route. Add a short video or request trace when timing matters, redact personal data and keep the original payload safe. If logs are needed, identify the relevant timestamp or correlation value rather than attaching an unreadable dump.
Close the loop after the first report
When a developer asks a question, update the report with the answer and the new evidence. If the issue cannot be reproduced, record what was tried instead of silently changing the claim. If it is fixed, rerun the smallest path and one nearby risk.
A useful report shortens the distance between observation and a team decision. It does not need dramatic language to make a defect actionable.
How to write a bug report: make one observation reproducible
Take one unexpected result from a small app or API. Write a title, starting state, minimum steps, expected result and actual result before adding any screenshot.
Ask whether someone with the same build and data could reproduce it from the text alone. Add only the missing context, then redact anything that should not leave the environment.
Finish with the boundary: frequency, affected path and what you did not test. This keeps a useful defect report from becoming a broad claim about every user.
Questions before the next step
- What is the smallest path that still shows the issue?
- Which observation separates expected from actual?
- Which context changes reproduction or priority?
- What should be redacted before sharing evidence?
Review defect management and other CTFL topics with focused questions and explanations.
Explore ISTQB Quiz →