How to Write an Ideal Bug Report? Template, Examples, and Best Practices

A bug report is the most important piece of communication between a tester and a developer. A good one gets fixed quickly. A poor one gets pushed down the backlog, bounced back for more information, or ignored altogether. The difference usually isn't writing talent. It's structure, evidence and clarity.

This guide explains what a bug report is, walks through every field you need, gives you a ready-to-use template and three worked examples, and shows how AI-native testing platforms now capture much of the evidence automatically.

What is a Bug Report

A bug report, sometimes called a defect report, is a written record of a software defect. It describes what's wrong, when it happens and what evidence shows it, so a developer can reproduce the problem and fix it. It's how QA formally hands a defect to the development team.

A good report gives the developer enough information to understand and reproduce the defect without coming back with questions. It also creates a record that can be tracked from the moment the defect is found to the moment it's closed, and over many releases those records show which kinds of defects keep appearing and where.‍

Bug Report vs Bug Log vs Bug Tracker

People often use these three terms loosely, so it helps to separate them.

What a Weak Report Costs the Team

A developer who receives a report with no reproduction steps, environment details or screenshots has to choose. They can investigate the problem themselves, which means debugging when they could be building, or they can send the report back and wait for answers. If QA and development work in different time zones, one round of questions can add a full working day before anyone starts on a fix.

Defects also get more expensive to fix the later they're found, because a problem caught in testing can be fixed before customers ever see it. That only helps if the report is clear.

A defect that's found but can't be reproduced from its report stays unfixed, which leaves the team almost where it would be if nobody had found it.

Essential Components of a Bug Report

Each of these fields gives the developer something they'd otherwise have to ask for. Leave one out and the report is more likely to be pushed down the backlog or sent back.

1. Bug ID

The tracker usually generates this automatically, for example JIRA-1234 or BUG-5678. It lets everyone point to the same defect in messages, code commits and release notes without describing it again.

2. Title

A good title tells a developer what's wrong before they open the report. It names the affected feature, describes the problem and states the condition that triggers it.

A title like "Button doesn't work" forces the developer to open the report to find out which button, on which page. Compare it with "Submit button on checkout page unresponsive when shipping address contains special characters", which names the button, the page and the trigger, so the developer can start thinking about the cause from the list view.

3. Description

The description explains the defect and its effect on users. Say whether it stops someone completing a purchase, produces a wrong calculation or shows incorrect information. Product managers and development leads use this to decide how urgently the defect needs fixing, so describe the impact in terms they'd recognise.

4. Environment

Record the operating system and version, the browser and version, the device type, the application version or build number, and the test environment, such as QA, staging or pre-production.

Many defects only appear in one setup. If a bug only happens in Safari on macOS, a developer testing in Chrome on Windows won't see it, and the report will probably come back marked "can't reproduce".

5. Steps to reproduce

These are the actions a developer follows to see the defect, and they're the most important part of the report. Write them so that someone who has never used the feature gets the same result you did.

"Go to checkout and try to pay. It doesn't work." gives the developer nowhere to start. Here's the same defect written as steps:

1. Go to the product catalogue page.

2. Add any product to the cart.

3. Click "Proceed to Checkout".

4. Enter a shipping address with an ampersand in the street field, for example "123 Smith & Sons Blvd".

5. Select "Credit Card" as the payment method.

6. Enter valid test card details.

7. Click "Submit Order".

8. Watch the Submit button stop responding, with no order confirmation shown.

6. Expected result

This describes what should happen when the steps are followed, for example: "The order is submitted and the user sees an order confirmation page with an order number." It gives the developer the baseline the defect is measured against.

7. Actual result

This describes what happens instead, including any error text exactly as shown, for example: "The Submit button stops responding and no confirmation appears. The browser console shows the error 'Uncaught TypeError: Cannot read properties of undefined (reading 'sanitize')'."

8. Severity

Severity describes how badly the defect affects the software. Most teams use four levels:

• Critical: the system crashes, data is lost, or a core function is broken with no workaround.

• High: a major feature is broken but the system keeps running, and any workaround isn't acceptable in production.

• Medium: a feature doesn't work as expected, but there's a reasonable workaround.

• Low: a minor issue, such as a typo or cosmetic flaw, that doesn't affect how the product is used.

9. Priority

Priority describes how soon the business needs the fix, and it's usually set by product management or the development lead. They weigh business impact, how many customers will see the problem and when the next release is due. A misspelt word on the homepage has low severity but may be high priority, because every visitor sees it. A crash in an admin tool used by two people has high severity but may be medium priority.

10. Attachments and evidence

Screenshots, a screen recording, browser console logs, network requests and responses, and relevant application log extracts all help. With good evidence, a developer can often find the cause before reproducing the defect at all, which is the fastest route to a fix.

Sample Bug Report Template

Field-by-field version

Plain-text version

Paste this into your tracker and fill in each line:

Common Bug Report Examples

1. A calculation defect in the cart

Title: Cart total shows the wrong amount after removing an item when a coupon is applied

Environment: Chrome 141 on Windows 11, staging environment, build 2.8.4

Severity: High. Priority: P1.

Description: When a customer applies a percentage coupon and then removes an item from the cart, the removed item's discount is subtracted a second time. The cart total ends up lower than it should be, and if the order goes through at that amount, the business loses money on it.

Steps to reproduce:

1. Add Product A ($50) and Product B ($30) to the cart.

2. Apply the coupon code "SAVE20" for 20% off.

3. Check the cart total shows $64, which is correct ($80 minus 20%).

4. Remove Product B from the cart.

5. Look at the cart total.

Expected result: The total recalculates to $40, which is Product A's $50 minus 20%.

Actual result: The total shows $34. Product B's $6 discount is taken off again after Product B has been removed.

2. A layout defect in mobile Safari

Title: Password field overlaps the "Forgot Password" link on the login form in mobile Safari

Environment: Safari 26 on iOS 26, iPhone 15 Pro, production environment

Severity: Medium. Priority: P2.

Description: In mobile Safari, the password field grows past its container and covers the "Forgot Password" link underneath. Users can't tap the link without tapping into the password field first, which makes it harder to recover an account.

Steps to reproduce:

1. Open the login page in Safari on an iPhone 15 Pro running iOS 26.

2. Tap the password field so the keyboard opens.

3. Look at the "Forgot Password" link below the field.

4. Try to tap "Forgot Password" while the keyboard is open.

Expected result: The password field stays inside its container and the "Forgot Password" link can be tapped.

Actual result: The password field covers the link, and tapping that area selects the password field.

3. An API defect that creates phantom orders

Title: Order API returns 200 OK but doesn't create an order record when stock is zero

Environment: QA environment, API v2.4, build 3.1.0

Severity: Critical. Priority: P1.

Description: The order creation endpoint returns 200 OK with an order number even when the product is out of stock. No order record is saved, but the customer still gets a confirmation email quoting that order number, so customers believe they've placed orders that don't exist.

Steps to reproduce:

1. Set the stock for product ID 4521 to 0 in the admin panel.

2. Send a POST request to /api/v2/orders with product ID 4521 and quantity 1.

3. Note the 200 OK response and the order_id in the response body.

4. Query the orders database for that order_id.

Expected result: The API returns a 400 or 422 error with a message saying there isn't enough stock.

Actual result: The API returns 200 OK with a generated order_id. The database has no record for it, and the confirmation email is still sent.

Severity Vs Priority - How Are They Different?

Severity and priority get confused more than any other fields, because both sound like "how bad is it".

Severity measures the technical impact and is usually set by QA. Priority measures business urgency and is usually set by product management or the development lead.

Because they measure different things, any combination is possible:

Include both fields in every report. When the priority isn't obvious from the severity, add a sentence explaining why you chose it.

The Bug Lifecycle: From Discovery to Closure

Understanding the bug lifecycle ensures that reports move efficiently through the resolution process rather than stalling in queues or bouncing between teams.

New

The defect has been reported and entered into the tracking system. It has not yet been reviewed by a developer or development lead.

Open / Assigned

The report has been reviewed, accepted as a valid defect, and assigned to a developer for investigation. If the report is rejected (not reproducible, duplicate, or by design), it moves to a Rejected or Closed status with an explanation.

In Progress

The assigned developer is actively working on a fix. This status indicates that the defect has been reproduced and a solution is being developed.

Fixed

The developer has implemented a fix and deployed it to a test environment. The fix is now ready for verification by the QA team.

Verified

The QA team has confirmed that the fix resolves the defect without introducing new issues. The verification should follow the original reproduction steps and also check for regression in related functionality.

Closed

The defect is resolved and verified. The bug report is closed and archived. If the defect reappears later, a new bug report should reference the original closed report for context.

Reopened

A previously closed defect has been observed again, either because the fix was incomplete or because a subsequent change reintroduced the issue. Reopened defects typically receive elevated priority.

Common Bug Report Mistakes and How to Avoid Them

1. Vague Titles

Titles like "page broken" or "error on click" force developers to open the full report before they can even assess relevance. Write titles that describe the defect specifically enough to be useful in a list view.

2. Missing Reproduction Steps

A bug report without reproduction steps is a feature request for investigation. Developers cannot fix what they cannot observe. If you can reproduce the defect, document every step. If you cannot reliably reproduce it, document the conditions under which you observed it and note that reproduction is intermittent.

3. Combining Multiple Defects in One Report

Each bug report should describe exactly one defect. Combining multiple issues in a single report creates confusion about when the report can be closed, makes tracking and metrics inaccurate, and complicates developer assignment when different defects require different expertise.

4. Missing Environment Details

"It works on my machine" is the most predictable response to a bug report without environment information. Always include the exact browser, OS, device, and application version. When testing across configurations, note which configurations exhibit the defect and which do not.

5. No Visual Evidence

A screenshot or video recording is worth more than a paragraph of description. Modern testing workflows should include visual evidence as a standard component of every bug report, not an optional addition.

Best Practices for Writing Effective Bug Reports

1. Write for the Reader, Not the Writer

The audience for a bug report is the developer who will fix the defect. Write with their needs in mind. They need to understand the problem, reproduce it, and verify the fix. Everything in the report should serve one of those three purposes.

2. Be Specific About Frequency

Is the defect consistent (happens every time the steps are followed) or intermittent (happens sometimes under certain conditions)? Intermittent bugs require more detail about the conditions under which they were observed and any patterns noticed (for example, "occurred 3 out of 10 attempts, always after the session exceeded 20 minutes").

3. Include What You Tried

If you attempted workarounds or variations, document them. "The defect occurs with Chrome 120 but not Firefox 121" immediately narrows the investigation scope. "The defect occurs with Product A and Product B but not Product C" suggests the issue may be product data related rather than code related.

4. Separate Observation from Interpretation

Report what you observed, not what you think the cause is. "The cart total shows $34 instead of $40" is an observation. "I think the discount calculation is wrong" is an interpretation. Include observations in the Actual Result section and interpretations in the Additional Notes section if they may be helpful.

5. Use Consistent Terminology

Refer to UI elements, features, and workflows using the same names that appear in the application and in internal documentation. Inconsistent terminology ("the pay button" vs "the submit order button" vs "the checkout CTA") creates confusion about which element is affected.

What AI changes about bug reporting

Gathering evidence, recording the environment and working out a likely cause take up most of the time spent on a bug report. AI-native testing platforms now handle a large share of that work while tests run.

Evidence captured while tests run

These platforms record a screenshot at each step, along with network requests and responses, the state of the page and the browser console output. When a test fails, that evidence is already attached to the result, so nobody has to recreate the failure to capture it.

The most common gap in a bug report, missing evidence, disappears for anything an automated test catches.

A likely cause before anyone investigates

A traditional report describes what went wrong. AI-assisted root cause analysis looks at the failed step, the network activity, the error messages and the page state, and suggests why it went wrong. The developer starts from a probable cause, which usually shortens the investigation.

Real defects separated from test problems

Some failed tests point to a broken product, and others point to an outdated test, an unstable environment or a timing problem.

When the team tags each failure with its reason, only genuine defects reach developers, and over a few releases the tags show where failures really come from.

Run reports that read like reproduction steps

A detailed run report shows each step that was attempted, what happened and whether it matched the expected result.

When the report also records which requirement the test covers, a failed run gives you most of a bug report already, along with a record of what was tested before the release.

How Virtuoso QA Changes the Bug Reporting Workflow

Virtuoso QA collects the evidence a bug report needs as part of every test run, so a failed test arrives ready to turn into a report.

At every step, it records a screenshot, network traffic, console output, the state of the page and performance data, on every run and without any setup. When a test fails, Root Cause Analysis shows the page at the moment of failure next to the same step from the last passing run, with the network and console detail alongside.

A "Why did this fail?" option gives a plain English explanation of the likely cause, often with a suggested fix, and the data used for that explanation stays inside Virtuoso. Teams tag each failure as an application bug, a test maintenance issue or an environment problem, so developers only receive genuine defects.

Each run also records the requirement behind every test and the person who approved the test, so a defect can be traced straight back to the requirement it breaks.