How to Write Clear Bug Reports in English
Author: Ksenia Izotova
Last updated: September 2026
Last updated: September 2026
The examples are illustrative. Use your team’s definitions of severity, priority and required evidence.
What makes a bug report clear?
A clear bug report lets another person identify the failure, reproduce it and decide what to investigate. Use a specific title, describe the conditions, list the shortest reliable steps, and separate expected behaviour from what actually happened. Add the environment, frequency and evidence that affect reproduction. Keep observations separate from your theory about the cause. If the issue is intermittent, say how often you saw it and what you tried. The report should reduce uncertainty without claiming more than the evidence shows.
“Checkout is broken” may be true from the reporter’s point of view. It leaves the developer to ask which checkout, which user, which device and what “broken” means.
“Checkout is broken” may be true from the reporter’s point of view. It leaves the developer to ask which checkout, which user, which device and what “broken” means.
Write a title that identifies the failure
A useful title usually contains the action or component, the observed failure and a condition that distinguishes the issue.
“Payment problem”
This could describe a declined card, a missing confirmation, a duplicate charge or a page that never loads.
“Card payment remains in Processing after 3-D Secure approval on iOS 18”
The second title can be scanned in a backlog. It also helps someone recognise a possible duplicate.
Do not put your proposed fix in the title unless the ticket is a task rather than a bug:
“Replace the payment callback”
That assumes the callback is the cause. The evidence may point elsewhere.
Mozilla’s bug-writing guidance recommends a clear, unique summary, precise steps to reproduce, and separate expected and actual results. It also advises separating observations from speculation. Source: Mozilla Bug Writing Guidelines
“Payment problem”
This could describe a declined card, a missing confirmation, a duplicate charge or a page that never loads.
“Card payment remains in Processing after 3-D Secure approval on iOS 18”
The second title can be scanned in a backlog. It also helps someone recognise a possible duplicate.
Do not put your proposed fix in the title unless the ticket is a task rather than a bug:
“Replace the payment callback”
That assumes the callback is the cause. The evidence may point elsewhere.
Mozilla’s bug-writing guidance recommends a clear, unique summary, precise steps to reproduce, and separate expected and actual results. It also advises separating observations from speculation. Source: Mozilla Bug Writing Guidelines
Describe what happened before explaining why
Start with the visible or measurable behaviour.
“After the customer completes 3-D Secure, the app returns to the order page and continues showing Processing for at least five minutes. No confirmation email is sent.”
Then add a hypothesis if it helps:
“The payment provider dashboard shows the payment as authorised. This may indicate that the callback is not updating the order status.”
The words “may indicate” matter. A log entry, a timing pattern or an engineer’s first impression is not yet a confirmed root cause.
“After the customer completes 3-D Secure, the app returns to the order page and continues showing Processing for at least five minutes. No confirmation email is sent.”
Then add a hypothesis if it helps:
“The payment provider dashboard shows the payment as authorised. This may indicate that the callback is not updating the order status.”
The words “may indicate” matter. A log entry, a timing pattern or an engineer’s first impression is not yet a confirmed root cause.
Four reports worth rewriting
“Login doesn’t work”
Why it causes delay: The developer cannot see the affected route, failure or conditions.
Clearer version:
“SSO login returns the user to the sign-in page after successful Okta authentication. Reproduced on the staging build 4.18.0 with an account that belongs to two workspaces.”
Clearer version:
“SSO login returns the user to the sign-in page after successful Okta authentication. Reproduced on the staging build 4.18.0 with an account that belongs to two workspaces.”
“Sometimes the page is broken”
Why it causes delay: “Sometimes” gives no frequency, trigger or observable result.
Clearer version:
“The dashboard opens without charts in 3 of 10 tests when the date range is changed before the initial data request finishes. Refreshing the page loads the charts.”
Clearer version:
“The dashboard opens without charts in 3 of 10 tests when the date range is changed before the initial data request finishes. Refreshing the page loads the charts.”
“User cannot check out. Critical.”
Why it can be misread: The report mixes observed impact with an unexplained severity label. It is unclear whether all users are affected.
Clearer version:
“A guest user cannot submit an order when the basket contains a subscription and a physical product. The Submit order button stays disabled. Logged-in users and single-product baskets were not affected in my tests.”
Apply your team’s severity rules separately.
Clearer version:
“A guest user cannot submit an order when the basket contains a subscription and a physical product. The Submit order button stays disabled. Logged-in users and single-product baskets were not affected in my tests.”
Apply your team’s severity rules separately.
“Expected result: it should work”
Why it causes delay: The developer still has to infer the intended behaviour.
Clearer version:
“Expected: After the user confirms the refund, the order status changes to Refunded and the refund reference appears in the activity log.”
Clearer version:
“Expected: After the user confirms the refund, the order status changes to Refunded and the refund reference appears in the activity log.”
Make the reproduction steps runnable
Start from a state another person can create.
Weak:
Weak:
- Open the account.
- Change the plan.
- Check the invoice.
Useful:
- Sign in to staging as an account owner with an active Monthly Basic plan.
- Open Settings → Billing.
- Select Annual Pro and confirm the change.
- Open the invoice created for the upgrade.
- Compare the tax amount with the billing address on the account.
Include test data only when it is safe to share. Never paste passwords, access tokens, personal customer data or sensitive production logs into a general issue tracker.
If a step depends on timing, state it:
“Select Export while the progress indicator is still visible.”
If order does not matter, do not create a false sequence. A short setup section may be clearer.
If a step depends on timing, state it:
“Select Export while the progress indicator is still visible.”
If order does not matter, do not create a false sequence. A short setup section may be clearer.
Separate expected and actual results
Expected behaviour explains the reference point. It may come from an acceptance criterion, design, specification or established behaviour.
- → Expected“The invoice uses the tax rate for the billing country saved before the plan change.”
- → Actual“The invoice uses the previous billing country. The account and checkout page both show the new address.”
Avoid emotional labels such as “wrong”, “weird” or “crazy” when a precise observation is available. “The total is €12 higher than the amount shown before confirmation” gives the team something to check.
Add the environment and evidence that matter
The useful details depend on the problem:
A screenshot can show the final state. A short recording can show timing. Logs can help locate the failure. None of them replaces the written steps and expected result.
Name attachments so they remain useful after download:
“checkout-disabled-ios18-build418.mov”
“request-7f31-redacted-log.txt”
Name attachments so they remain useful after download:
“checkout-disabled-ios18-build418.mov”
“request-7f31-redacted-log.txt”
Keep severity and priority separate
Severity describes the effect of the defect under your team’s model. Priority describes when the work should be done. A severe issue may have low immediate priority if the affected feature is disabled. A smaller defect may need urgent attention before a public demo.
If you do not own the priority decision, report the impact:
“All guest checkouts using mixed baskets failed in the tests I ran. I have not yet checked how many orders used this route.”
Only include a number when you have the source and permission to share it. Otherwise:
“The affected route is available to all guest users. I have not confirmed how many sessions encountered the failure.”
If you do not own the priority decision, report the impact:
“All guest checkouts using mixed baskets failed in the tests I ran. I have not yet checked how many orders used this route.”
Only include a number when you have the source and permission to share it. Otherwise:
“The affected route is available to all guest users. I have not confirmed how many sessions encountered the failure.”
A bug report template
Your tracker may use different fields. The information should still be easy to find.
Check the report before submitting
- Can someone distinguish this issue from similar tickets by the title?
- Do the steps start from a known state?
- Have you written the action, not only the intention?
- Are expected and actual results separate?
- Is the root-cause theory labelled as a theory?
- Have you stated frequency and environment?
- Does the impact describe what you confirmed?
- Are attachments named, relevant and free of secrets or personal data?
- Should this be one report or several separate issues?
Frequently asked questions
How long should a bug report be?
Long enough to reproduce and assess the issue. A simple UI defect may need six lines and one screenshot. An intermittent integration failure may need timestamps, IDs and several checks. Extra history does not help when the reproduction route is missing.
Should I correct all grammar before submitting?
Correct wording that changes the meaning, especially negatives, conditions, dates and expected results. Simple English is fine. A clear sequence and accurate evidence matter more than sophisticated vocabulary.
What should I write if I cannot reproduce the bug?
State exactly what you observed, when it happened and what evidence remains. List the attempts that did not reproduce it. The report may still be useful when it contains a unique request ID, crash trace or customer pattern.
Should one report contain several related bugs?
Usually each independently testable failure needs its own report. Link the tickets and explain the shared context. This makes ownership, verification and release decisions easier.
Test the report with a handover
Give the report to someone who did not watch you find the issue. Notice where they pause or make an assumption. That is usually where the writing needs another condition, action or result.
UnifyHub’s English for QA engineers programme covers bug reports, testing discussions and handovers. Book a team assessment to identify the written and spoken situations your QA team handles. For urgent production failures, read how to communicate during an incident.
UnifyHub’s English for QA engineers programme covers bug reports, testing discussions and handovers. Book a team assessment to identify the written and spoken situations your QA team handles. For urgent production failures, read how to communicate during an incident.
Author: Ksenia Izotova
Last updated: September 2026
Last updated: September 2026