How to write a good bug report (with template and examples)

A good bug report lets another person see the problem, reproduce it, and judge its impact without starting a long question-and-answer thread. It does not need to be long. It needs to contain the right evidence in a predictable structure.

The fastest way to get that structure is to use the free bug report template generator. Fill in what you know, choose Markdown, Jira, or plain text, and copy a clean report into your tracker. Nothing you type is uploaded.

What should a bug report include?

Most useful software bug reports contain seven parts:

• A specific, searchable title
• The environment in which the bug occurred
• Numbered steps to reproduce it
• The expected result
• The actual result
• A severity based on user and system impact
• Evidence such as screenshots, logs, video, or exact error messages

These fields separate observation from interpretation. The steps describe what the tester did; the expected and actual results show the discrepancy; the environment and attachments help engineering explain it.

A bug report template you can copy

# [Feature]: [Specific problem and condition]

## Environment

- Device or browser:
- OS:
- App version or build:
- Account or test data:

## Steps to reproduce

1. Start from...
2. Open...
3. Enter or select...
4. Observe...

## Expected result

[What should happen]

## Actual result

[What happens instead, including exact error text]

## Severity

[Low / Medium / High / Critical, with a short reason]

## Evidence

[Screenshot, recording, logs, request ID, or console output]

You can adapt the headings to match your team’s tracker. Consistency matters more than the precise labels. If you would rather fill in a form than edit a block of text, the free bug report generator creates the same structure and omits any fields you leave blank.

How do you write a useful bug report title?

Write the title after reproducing the issue. A strong title names the affected area, the visible failure, and the condition that triggers it.

Compare these examples:

Weak title	Better bug report title
Login broken	Login: valid SSO account returns “Session expired” after redirect
App crashes	Profile: app closes when uploading a PNG larger than 10 MB
Wrong total	Basket: discount is applied twice after quantity changes from 1 to 2
Button issue	Checkout: Pay now stays disabled after entering a valid UK postcode

Avoid diagnosing the cause unless you have evidence. “Null pointer in the payment service” may send the investigation in the wrong direction; “Payment screen closes after tapping Pay now” records what actually happened.

How do you write steps to reproduce a bug?

Begin from a state another tester or developer can recreate. “Go to checkout” is ambiguous if it depends on a signed-in account, a particular product, or a feature flag. Name those preconditions in the environment or first step.

Then follow four rules:

1. Put one action in each step.
2. Use exact labels, values, and test data where they matter.
3. Include the final action that triggers the failure.
4. Run the written steps once before submitting them.

For an intermittent issue, add the reproduction rate: for example, “3 of 10 attempts on a throttled network.” Do not turn a guess into certainty. A clear report can say that a bug is inconsistent.

Expected result vs actual result

The expected result states the behaviour the product is supposed to provide. The actual result states what you observed instead. Keep them separate even when the contrast feels obvious.

For example:

Expected: After a valid card payment, the order confirmation page opens and shows the order number.

Actual: The Pay now button shows a spinner for 30 seconds, then returns to its normal state. No confirmation appears and the basket remains full.

This is more useful than “payment failed.” It tells engineering which transition did not occur and which state remained behind.

What environment details matter?

Record details that could change the result:

• Device model or browser and version
• Operating system and version
• App version, build number, or commit
• Screen size or orientation for visual bugs
• Locale, timezone, permissions, and network conditions
• Account role, feature flags, and relevant test data

The goal is not to fill every field for every bug. A desktop browser version may be irrelevant to a backend calculation error, while orientation is crucial for a mobile layout failure. Include the conditions needed to reproduce or narrow the problem.

How should you choose bug severity?

Severity describes impact, not how annoying the bug felt during testing. A practical scale is:

• Low: cosmetic or minor friction with no meaningful loss of function.
• Medium: a feature is impaired, but a reasonable workaround exists.
• High: an important workflow is blocked or data may be incorrect.
• Critical: widespread crash, security exposure, data loss, or a core system unavailable.

Your team’s definitions should win if they differ. Add one sentence explaining the impact when the choice is not obvious. Also keep severity distinct from priority: product and engineering may raise or lower the fix order based on reach, deadlines, risk, and strategic importance.

A complete bug report example

# Checkout: Pay now stays disabled after entering a valid UK postcode

## Environment

- Pixel 8, Android 16
- App build 2.14.0 (842)
- Test buyer account, locale en-GB

## Steps to reproduce

1. Sign in with the test buyer account.
2. Add any in-stock item to the basket.
3. Open Checkout and select Add a new address.
4. Enter postcode SW1A 1AA and select the returned address.
5. Complete every remaining required field.

## Expected result

The Pay now button becomes enabled after the valid address is selected.

## Actual result

The Pay now button remains disabled. No validation message appears.

## Severity

High — the customer cannot complete checkout and there is no workaround in the app.

## Evidence

Screenshot attached. Recent logs show the address request returned 200.

The report is compact, but it gives the developer a reproducible path, a build, test conditions, the visible result, and an impact statement.

Common bug reporting mistakes

• Combining several unrelated problems in one ticket
• Using vague titles that are impossible to search or distinguish
• Describing the intended fix instead of the observed behaviour
• Leaving out the build, browser, device, or account state
• Pasting a screenshot without writing reproducible steps
• Paraphrasing an error instead of copying its exact text
• Marking every frustrating bug as critical

Templates prevent omissions, but they should not encourage padding. A concise report with complete evidence is better than a long form filled with irrelevant details. Use the bug report template generator to build the structure, then attach the evidence that makes this particular issue reproducible.