How to Write a Good Defect Report in Software Testing

Finding a defect is only the first half of a tester’s job. The second is communicating it well enough for another person to reproduce, understand, prioritise, and verify.

A developer should not need a meeting to discover which build failed, what data was used, or what the tester expected to happen. At the same time, a defect report should not contain several pages of unrelated technical information that hide the actual problem.

The best defect reports are complete but concise. They establish the starting state, describe one problem, provide repeatable steps, separate expected and actual behaviour, explain the impact, and attach evidence that helps the team investigate.

This guide explains every important field in a defect report, how to write reliable reproduction steps, how to report intermittent issues, and which mistakes make valid defects unnecessarily difficult to resolve.

What Is a Defect Report?

A defect report is a structured record describing a difference between expected and observed software behaviour.

It gives developers, product owners, QA engineers, support teams, and release managers the information needed to evaluate the issue and move it through the defect lifecycle.

A useful report should help the team answer five questions:

1. What went wrong?
2. Where and under which conditions did it happen?
3. How can another person reproduce it?
4. What should have happened instead?
5. How seriously does it affect users or the business?

A defect report is not merely proof that something looks wrong. It is an investigation hand-off. The tester has observed the failure and must transfer enough context for another person to continue the work without reconstructing the entire scenario.

Bug Report vs Defect Report

The terms “bug report” and “defect report” are commonly used interchangeably.

Some organisations use “defect” for any deviation from requirements and “bug” for an error in the implementation. Others use one term consistently for all product issues.

The team’s shared workflow matters more than the label. Whether the ticket is called a bug, defect, incident, or issue, it should describe the behaviour clearly and support reproduction, triage, resolution, and verification.

Why Is a Good Defect Report Important?

It reduces reproduction time

Exact steps, data, environment details, and evidence allow developers to reach the failure without guessing what the tester did.

It improves prioritisation

A report explaining that a defect blocks all users from completing payment provides more useful triage information than a title saying “Checkout not working.”

It prevents misunderstanding

Separating expected and actual outcomes makes the disputed behaviour explicit. Product and engineering teams can then determine whether it is a defect, missing requirement, intended behaviour, or enhancement request.

It supports accurate verification

After the fix, the same report provides the scenario needed for confirmation testing and related regression testing.

It preserves product knowledge

The report records when the problem appeared, which version contained it, how it affected users, and how it was resolved. This information can support future root-cause analysis and defect prevention.

Anatomy of a Good Defect Report

Not every organisation needs every field for every defect. A spelling error does not require database logs, while an intermittent payment failure may require network traces, timestamps, transaction identifiers, and backend evidence.

1. Write a Specific Defect Title

The title should allow someone scanning a backlog to understand the problem without opening the ticket.

A useful structure is:

Affected area + condition + observed failure

Weak title:

Login issue

Better title:

Login button remains disabled after correcting an invalid email address on Android

The improved title identifies the feature, triggering condition, failure, and affected platform.

Other examples:

Checkout creates duplicate orders when the payment response times out

Invoice total excludes tax after changing the billing country to Germany

Profile image is removed after cancelling the crop dialog on iOS

Viewer role can export administrator-only reports through the API

Avoid titles such as “Does not work,” “Error found,” “Please fix,” or “Major bug.” These communicate neither behaviour nor context.

Do not include the entire reproduction sequence in the title. It should remain concise enough to scan in boards, notifications, and release reports.

2. Record the Correct Build and Environment

Environment information helps determine whether the issue is universal or specific to one configuration.

Include what is relevant to the product:

• Application version or build number
• Test, staging, or production environment
• Operating system and version
• Browser and version
• Device model
• Screen size or orientation
• API version
• Database or service version
• Feature-flag state
• Network condition
• Account type or user role
• Locale or language

Instead of writing:

Tested on Android

Write:

Staging; app build 6.4.2 (1048); Pixel 8; Android 16; Wi-Fi; returning customer account; new_checkout flag enabled.

Use current tool-generated values where possible. Manual environment fields become inaccurate when testers copy old reports and forget to update them.

3. State the Preconditions

Preconditions describe the state required before the first reproduction step.

Examples include:

• User is logged in as an organisation administrator.
• The account contains at least one unpaid invoice.
• The cart contains a subscription and a physical product.
• The user has denied location permission.
• The feature flag is enabled.
• The account currency is EUR.
• The app was upgraded from version 5.8 to 6.0.

Without preconditions, another tester may follow the steps correctly but start from a different state and never see the failure.

Keep preconditions separate from actions. “Log in” is a reproduction step if it contributes to triggering the problem. “User is already logged in” is a precondition if login itself is irrelevant.

4. Include the Exact Test Data

A defect may depend on a particular value, record, file, account state, date, or data combination.

Record test data such as:

• Username or test-account reference
• Product or order identifier
• Input values
• Currency and amount
• Uploaded file name, type, and size
• Date and time
• API payload
• Search term
• Role and permission combination

Do not include real passwords, access tokens, payment details, private customer information, or other secrets in a ticket. Use approved test accounts, masked values, secure attachments, or internal references.

If the defect appears only with a specific production record, follow the organisation’s data-handling procedure rather than copying sensitive data into the report.

5. Write Reproducible Steps

Reproduction steps should allow another person to trigger the same behaviour without interpretation.

GitHub’s standard bug-report forms similarly separate current behaviour, expected behaviour, reproduction steps, environment, and additional context. Its documentation recommends requesting the actions required to trigger the issue step by step.

Start From a Known State

Specify where the person should begin:

1. Sign in to the staging app as an account administrator.
2. Open Billing > Invoices.
3. Select invoice INV-10482.
4. Select Download PDF.
5. Observe the generated file.

Avoid beginning midway with “Download the invoice.” The reader may not know which account, invoice, page, or access level is required.

Use One Action Per Step

Weak:

Log in, navigate to checkout, add a coupon and complete payment.

Better:

1. Sign in using the returning-customer test account.
2. Add product SKU-142 to the cart.
3. Open the cart.
4. Enter coupon LOYAL20.
5. Select Apply.
6. Proceed to checkout.
7. Select Pay now.

Separating actions makes it easier to determine exactly when the result diverges.

Name Controls and Values Precisely

Write “Select Save address” instead of “Click the button.”

Write “Enter 99999 in the Postal code field” instead of “Enter invalid details.”

Include Timing When It Matters

Intermittent and asynchronous defects may depend on timing:

Immediately select Pay again before the loading indicator disappears.

Leave the screen in the background for more than five minutes before returning.

Do not add timing details unless they are relevant.

End With the Observation

The final step should lead directly to the reported behaviour:

Observe that two orders are created with different order IDs.

This makes the hand-off from actions to actual result clear.

6. Define the Expected Result

The expected result describes the correct behaviour.

It should be based on a reliable source, such as:

• Acceptance criteria
• Requirement
• Design specification
• API contract
• Business rule
• Accessibility standard
• Previous approved behaviour
• Product-owner confirmation
• Platform guideline

Weak:

It should work properly.

Better:

One order should be created for the payment attempt, and subsequent requests with the same idempotency key should return the existing order.

If the expected result is unclear, do not invent one. Record the uncertainty and ask the relevant product or business owner to confirm whether the observed behaviour is incorrect.

A discrepancy can reveal a requirement gap rather than a coding defect.

7. Describe the Actual Result Objectively

The actual result should state exactly what the system did.

Weak:

The payment system is broken because the API is probably timing out.

Better:

Two confirmed orders are created for one payment attempt. Order IDs ORD-7814 and ORD-7815 contain the same customer, cart, amount, and payment reference.

The first statement mixes observation with an unverified technical theory. The second gives facts the team can investigate.

Include:

• Visible behaviour
• Exact error text
• Status codes
• Incorrect values
• Missing records
• State changes
• Whether the app crashed, froze, or recovered
• Relevant timestamps or identifiers

Copy error messages exactly rather than paraphrasing them.

8. Report the Reproduction Frequency

Not every defect occurs consistently. Frequency helps the team estimate reproducibility and investigation risk.

Use evidence such as:

Reproduced 5 out of 5 attempts on Android 16.

Reproduced 2 out of 10 attempts when switching from Wi-Fi to cellular during upload.

Reproduced consistently with organisation-admin accounts but not with standard-member accounts.

“Occurs randomly” provides little diagnostic value. If the pattern is unknown, report the number of attempts and every condition you tested.

For intermittent defects, record:

• Approximate frequency
• Time of occurrence
• Actions immediately before failure
• Device load or network condition
• Whether retrying succeeds
• Whether restarting changes the result
• Affected and unaffected configurations
• Request, session, transaction, or trace identifier

9. Explain the Impact

Impact explains why the defect matters.

Severity labels can be interpreted differently, but an impact statement provides concrete context:

All users are prevented from completing checkout because the Pay button remains disabled.

The defect affects display only; the correct amount is charged and stored.

A user with Viewer access can download reports containing employee salary information.

Approximately 8% of production uploads fail on files larger than 20 MB, based on monitoring from the last 24 hours.

Impact should be factual. Avoid exaggeration such as “This completely destroys the user experience” unless the report contains evidence supporting that conclusion.

10. Assign Severity and Priority Correctly

Severity describes the effect of the defect on the product.

Priority describes how urgently the organisation wants it corrected.

A defect can have high severity but lower immediate priority if it affects an unreleased, disabled feature. A visually minor defect can have high priority when it appears in a prominent campaign immediately before launch.

A typical severity model might be:

Teams should define their own criteria. The tester may propose severity based on impact, while product or engineering leadership determines priority during triage.

Do not inflate severity to attract attention. Repeated misclassification weakens trust in future reports.

11. Attach Relevant Evidence

Evidence helps communicate what words cannot and supports diagnosis.

Screenshots

Use screenshots for:

• Layout problems
• Incorrect text or values
• Missing controls
• Visual states
• Error messages

Annotate the relevant area without covering important context.

Screen Recordings

Use recordings for:

• Animation or timing problems
• Multi-step interactions
• Intermittent UI behaviour
• Gesture defects
• Unexpected navigation
• Crashes or freezes

The video should support, not replace, written reproduction steps.

Logs and Traces

Attach or link:

• Browser-console output
• Network requests and responses
• Application logs
• Mobile device logs
• Crash reports
• Distributed traces
• Relevant database evidence
• CI/CD execution logs

Trim irrelevant noise where possible and identify the important timestamp, request, or error.

Protect Sensitive Information

Before attaching evidence, remove or mask:

• Passwords
• Tokens
• API keys
• Payment details
• Personal information
• Private customer records
• Confidential internal URLs

Access to the ticket may be wider than access to the underlying production system.

12. Add Scope and Comparison Observations

Information about where the defect does and does not occur helps narrow the investigation.

Examples:

Reproducible in Firefox on Windows, but not in Chrome or Edge using the same account and data.

Occurs for EUR transactions but not USD transactions.

Reproducible when the feature flag is enabled; behaviour is correct when disabled.

Affects accounts created before the migration but not newly created accounts.

These observations are particularly useful for intermittent, compatibility, migration, permission, and configuration defects.

Do not delay a critical report merely to test every possible variation. Submit the essential issue and add confirmed scope information as it becomes available.

Complete Defect Report Template

Use this template as a starting point and adapt it to the project.

Title

[Feature or component] + [condition] + [observed failure]

Environment

Environment:
Application version/build:
OS/device/browser:
API or service version:
Feature flags/configuration:
User role/account type:
Network or locale, if relevant:

Preconditions

Describe the required starting state.

Test Data

List the safe test accounts, records, values, or files required.

Steps to Reproduce

Expected Result

Describe the correct behaviour and reference the requirement where available.

Actual Result

Describe the exact observed behaviour.

Reproduction Rate

For example: 5/5 attempts or 2/10 attempts.

Impact

Explain who is affected and what they cannot do or what risk is created.

Severity

Critical / High / Medium / Low, according to team definitions.

Evidence

Screenshots:
Recording:
Logs/traces:
Request or transaction ID:

Scope Notes

Affected configurations:
Unaffected configurations:
First known version:
Workaround, if confirmed:

References

Requirement:
Test case:
Related issue:
Release or code change:

Example of a Good Defect Report

Title

Checkout creates two confirmed orders when payment is retried after a client timeout

Environment

Staging environment
Web build: 2026.07.31.4821
Chrome 150 on macOS 15.6
Account: returning customer, EUR currency
Payment provider sandbox
Network throttled to high latency

Preconditions

The user is signed in and has one in-stock product in the cart. No existing order has been created for the cart.

Test Data

Product: SKU-142
Quantity: 1
Test card: approved sandbox card
Cart total: €49.00

Steps to Reproduce

1. Open the cart.
2. Select Proceed to checkout.
3. Enter the approved test-card details.
4. Apply high-latency network throttling.
5. Select Pay now.
6. Wait until the client displays “Request timed out.”
7. Select Try payment again.
8. Open My Orders.

Expected Result

Only one order should be created for the cart. Retrying the same payment attempt should return or resume the existing transaction.

Actual Result

Two confirmed orders are created: ORD-7814 and ORD-7815. Both contain the same cart, amount, customer, and payment reference.

Reproduction Rate

Reproduced 4 out of 5 attempts under high latency. Not reproduced on a stable connection in 5 attempts.

Impact

Customers may place duplicate orders after a timeout and may require cancellation or refund assistance. Inventory is reserved twice.

Severity

Critical

Evidence

Screen recording attached
Network trace attached
Payment reference: PAY-229104
Server timestamps: 14:32:11 and 14:32:18 IST

Scope Notes

Reproduced with card payments. Not reproduced with wallet payments.

This report does more than say that duplicate orders exist. It defines the starting state, exact trigger, evidence, frequency, affected scope, and customer impact.

Weak vs Strong Defect Reports

Weak Title

Search not working

Strong Title

Product search returns an empty page for queries containing an apostrophe in Firefox

Weak Steps

Open search and try a product name.

Strong Steps

1. Open the product catalogue in Firefox.
2. Enter Farmer's Market in the search field.
3. Select Search.
4. Observe the results area.

Weak Expected Result

Results should appear normally.

Strong Expected Result

Products matching the complete query should be displayed, including Farmer's Market Tote.

Weak Actual Result

Search is broken.

Strong Actual Result

The results area remains blank and the console displays SyntaxError: Unexpected token after submission.

The strong version replaces interpretation with reproducible observations.

How to Report an Intermittent Defect

Intermittent issues require additional evidence because the reproduction sequence may not succeed every time.

Begin by preserving the first occurrence. Record the exact time, build, account, device, network, preceding actions, and identifiers before restarting or clearing the state.

Then vary one condition at a time:

• Browser or device
• Network speed
• Account role
• Data size
• Feature flag
• Cache state
• Repetition count
• Timing
• Background or foreground state

Report both positive and negative findings. “Occurs twice in ten attempts under packet loss but zero times on a stable network” is useful even without a guaranteed sequence.

Do not refuse to report a high-impact issue solely because it is not consistently reproducible. Mark it accordingly, attach the available evidence, and explain what investigation has already been performed.

Should a Defect Report Include the Possible Root Cause?

It may include a technical hypothesis when it helps investigation, but the hypothesis must be labelled clearly.

Good:

Possible lead: both failed requests returned HTTP 504 from the pricing service. This has not yet been confirmed as the root cause.

Poor:

Root cause: the pricing database is slow.

The second statement presents an assumption as fact.

A tester’s main responsibility is to report observable behaviour and supporting evidence. If logs, code, traces, or a controlled experiment confirm the cause, add that evidence. Otherwise, keep diagnosis separate from observation.

Best Practices for Writing Defect Reports

Report One Primary Problem Per Ticket

Separate unrelated defects so they can be prioritised, assigned, fixed, and verified independently.

If several symptoms clearly share one underlying event, keep them together and explain the relationship.

Reproduce Before Submitting

Repeat the scenario whenever safe and practical. Confirm the environment, simplify the steps, and collect evidence.

Do not repeatedly reproduce destructive production issues if doing so could harm users or data.

Search for Duplicates

Look for existing reports using the feature, error message, component, and observed behaviour. Add new evidence to the existing ticket where appropriate.

GitHub and other issue-management systems support bug-report templates specifically to encourage consistent, useful information. GitHub Docs

Be Concise but Complete

Include information that helps reproduce, assess, diagnose, or verify. Remove history and speculation that do not support those goals.

Keep the Tone Neutral

Describe the product behaviour rather than blaming the person who implemented it.

Write:

The API returns records belonging to another organisation.

Avoid:

The developer forgot to implement security properly.

Link Related Artefacts

Connect the report to the requirement, test case, release, pull request, incident, monitoring alert, and related defects where available.

Update the Report as Knowledge Changes

If the frequency, affected scope, workaround, or expected result changes, update the main report instead of leaving essential information buried in comments.

Common Defect-Reporting Mistakes

Vague Titles

Titles such as “Page issue” or “Functionality broken” make triage and duplicate detection difficult.

Missing Preconditions

The steps may be correct, but the developer begins with the wrong account state, role, configuration, or data.

Combining Several Defects

A report containing a layout issue, calculation error, and crash cannot be assigned or closed cleanly.

Mixing Expected and Actual Results

Keeping them separate makes the deviation explicit and simplifies verification.

Assuming the Cause

An unverified theory can send the investigation in the wrong direction.

Attaching Evidence Without Written Context

A ten-minute recording or massive log file should not force the developer to search for the actual failure.

Incorrect Severity

Classify severity using agreed impact criteria, not personal frustration.

Omitting Frequency

The difference between 10 out of 10 attempts and 1 out of 100 can influence investigation and release decisions.

Using Outdated Copied Details

Copied tickets frequently retain the wrong build, browser, account, or expected result. Verify every field before submission.

Creating Better Defect Report Templates

A standard template improves consistency, but too many mandatory fields can encourage low-quality placeholder text.

Make fields mandatory when they are useful for most reports:

• Title
• Build or version
• Environment
• Steps
• Expected result
• Actual result
• Impact
• Reproduction rate

Use conditional fields for mobile device details, network traces, accessibility settings, API information, or database evidence.

Templates should guide thought, not create administrative work. Review them when the team repeatedly asks the same clarification or when fields are consistently left irrelevant.

Frequently Asked Questions

What makes a defect report effective?

An effective report describes one issue, starts from a known state, provides reproducible steps, separates expected and actual behaviour, records the environment and data, explains impact, and includes relevant evidence.

What should be included in a defect title?

Include the affected feature or component, the important triggering condition, and the observed failure. For example: “Checkout creates duplicate orders when payment is retried after a timeout.”

Why are reproduction steps important?

They allow another person to trigger the same behaviour, investigate its cause, verify the correction, and create regression coverage without repeatedly asking the original reporter for clarification.

What if a defect cannot be reproduced consistently?

Report the number of attempts, occurrence frequency, timestamp, environment, preceding actions, affected and unaffected conditions, and all available logs or identifiers. Intermittent high-impact defects should not be ignored.

Should a defect report include a proposed solution?

A suggestion may be included when it is evidence-based, but it should not replace the behaviour report. Avoid presenting an unverified technical assumption as the required fix.

What is the difference between severity and priority?

Severity describes the defect’s effect on the product, users, data, or security. Priority describes how urgently the organisation wants the issue addressed relative to other work.

Should screenshots always be included?

No. Include screenshots when they make the issue clearer. Use recordings for timing or interaction problems and logs or traces for technical failures. Evidence should support the report, not add noise.

Who assigns defect priority?

The tester may propose a priority, but product, engineering, QA, support, or release stakeholders commonly agree on it during triage based on impact, timing, business commitments, risk, and available workarounds.

How long should a defect report be?

It should be as short as possible while remaining reproducible and actionable. A cosmetic issue may need a few fields and a screenshot; an intermittent transaction failure may require extensive diagnostic context.

Can a defect report be rejected?

Yes. A ticket may be closed as duplicate, intended behaviour, insufficient information, unreproducible, environment-related, configuration-related, or an enhancement. The reason should be documented rather than dismissed without explanation.

Conclusion

A good defect report turns an observation into work the team can act on.

Its value does not come from length or technical vocabulary. It comes from removing uncertainty. A clear title identifies the failure, precise environment details recreate the conditions, numbered steps reproduce the behaviour, and separate expected and actual results establish the deviation.

Impact, frequency, severity, and evidence then help the team decide how urgently the issue should be investigated and provide the context needed to diagnose it.

The strongest testers do not merely find more defects. They communicate each important defect in a way that makes it difficult to misunderstand, easy to reproduce, and straightforward to verify after correction.

When defect reports consistently meet that standard, development and QA spend less time clarifying tickets and more time improving the product.