How to write effective bug reports [Step-by-step guide]

Writing a bug report isn’t exactly rocket science. All you need is to capture a screenshot or video, document the steps to reproduce the issue, add technical details, provide a brief explanation of what went wrong, and send it off to the developers. Sounds pretty straightforward, right? Well, hold your horses. 

The traditional bug reporting process often follows a routine, by-the-book steps where you paste reports into a bug tracker. However, if key information is left out or overlooked, turnaround times can increase significantly. And this often leads to wasted efforts, endless email chains, and even friction among teammates. 

The result? The report might get rejected by the developers. Or worse, buried in your backlog, waiting for someone to stumble upon it. So, what’s the fix? Well, a well-written bug report can make all the difference. 

A bug report is a formal document with the necessary details to visualize, reproduce, diagnose, and fix a software issue. Its primary aim is to provide developers with the firsthand information, complete context, and technical details if something goes wrong or isn’t working as expected in the application. 

Quality assurance (QA) members, testers, developers, stakeholders, and even end-users can create bug reports. Developers can then analyze the report, reproduce the issue, and work on fixing it in a given timeframe.

Also Read: Quality Assurance vs. Quality Control

Key fields in a bug report:

• Bug title — A concise, easily searchable, and one-liner title that quickly explains the issue. It might also indicate the affected component and the nature of the error.
• Summary/Description — A quick summary of the issue for additional context (without using overly technical language).
• Expected vs. actual result — A quick overview of “what should happen” vs “what’s actually happening”.
• Steps to reproduce the bug  — Verbose, step-by-step, and easy-to-follow numbered instructions to reproduce the issue (with all the details).
• Bug priority — How fast the issue needs to be resolved. Options: Urgent, High, Medium, Low
• Bug severity — The effect of the issue on the functionality: Options: Blocker, Critical, Major, Medium, Trivial
• Environment details — Technical details, such as URL, system information, browser specs, device details, reporter info, network speeds, console logs, network requests, and others.
• Supporting documents — Attachments and files relevant to the issue.
• Visual proof of the issue — An image or video of the issue, including any error messages, with annotations to highlight key details.

Here are the key elements of a good bug report and pressing questions that these elements should clearly explain to the developers:

1. What’s the issue? — The bug title and a summary with a crisp explanation works best.
2. Any visual proof of the issue? — Screenshots or video recordings.
3. Any additional context that should be considered? — Annotations on the screenshot OR attached video message/voiceovers with the video recording.
4. Where does the bug occur? — A specific URL, app page, feature, or module.
5. When does the issue happen? — Does it occur everytime or only under certain conditions?
6. What were you (as a reporter) exactly doing when the issue occurred? — Steps to reproduce the issue.
7. What’s the expected behavior and what’s really happening? — Expected vs actual result in the description
8. What are the environmental details? — Operating system, device details, network speed, timestamp
9. Any technical details about the issue? — Console logs, navigation steps, error messages, warnings, network requests, and cookies.
10. How severe is the issue and what’s the priority level? — Severity and priority levels.
11. Are there any documents or files? — Attached files, such as requirement traceability matrix(RTM), project spec sheets, requirement documents, or documentation.

Also Read: How to write test cases? [Step-by-step guide with examples]

Steps to write effective bug reports:

Step 1: Take a screenshot or record a video of the issue

Start by taking a screenshot or a video recording of the issue. Add any annotations or highlight areas that help pinpoint the issue. You can use a visual bug reporting tool such as BetterBugs to instantly take screenshots or record screens for a bug report.

Also Read: Why every CI/CD pipeline needs a visual bug tracker?

Step 2: Add a clear and concise bug title 

Add a title for the report. Keep it short, simple, and precise. The title should contain specific technical terms related to the issue. It's best to avoid using vague terms, verbose explanations, or an authoritative tone. 

Also, make sure that the title is unique. This prevents you from creating a duplicate ticket and ensures that the title can be used as a keyword while filtering it in a bug tracking or project management tool.

Example:

• Good title: Uploading an Image File (JPEG, JPG, and others) in User Profile Settings Crashes the App.
• Bad title: System shows error when uploading a file.

Note: You can also add a defect ID with a naming convention followed by your team. Or if you’re using a bug tracking tool, such as Jira, Linear, or others, the defect ID will automatically be assigned by them.

Step 3: Describe the issue 

Next, summarize the issue in plain, polite, and non-technical language(wherever possible). Avoid using authoritative or vague terms or descriptions.  

Example:

• Good description: When a user attempts to upload an image file (JPEG, JPG, PNG, etc.) in the User Profile Settings, the application reloads and eventually crashes. The crash occurs regardless of image size, resolution, or file type. I’ve attached error messages and warnings in the console that are displayed before the crash. PFA text documents for the logs.
• Bad description: Uploading profile images crashes the app. Fix it ASAP.

Step 4: Explain the intended behavior and the actual outcome 

Next, outline the correct behavior, i.e., what the application is meant to do in an ideal scenario, and then detail the unintended behavior. Consider using descriptive language without exaggerating.

Example:

• Expected Behavior: Tapping the "Save" button should update the user’s profile and confirm the change with a success message.
• Actual Outcome: Upon tapping the "Save" button, the profile page reloads unexpectedly, the changes are not saved, and the app crashes, throwing a 500 internal server error.

Step 5: Add the steps to reproduce the issue 

List out each step needed to consistently recreate the issue. Break down the process into clear, numbered steps that someone unfamiliar with the issue can easily follow. Detail every relevant interaction (even those that might seem obvious) to make sure that the issue can be reliably reproduced.

Example:

1. Log in to the app using valid credentials.
2. Click on the "Settings" icon in the upper-right corner.
3. Scroll down to the "Profile" section and hit the "Upload Image" button.
4. Choose a JPEG file from your device and hit the “Confirm” button.
5. Notice that the app reloads, crashes, and ultimately shows a 500 internal server error message.

Step 6: Include environment and technical details (logs, error messages, network requests, and warnings)

Capture technical details that might be causing the issue. Provide information including the browser type and version, operating system, device specifications, and any relevant network conditions. Supplement your report with logs or error messages, as these technical clues can be critical in diagnosing the underlying issue.

Example: 

Environment details

• URL: https://example-store.au
• Operating system: Windows 11 
• Browser: Chrome 119 
• Device: Lenovo ThinkPad 15
• Error Message: "Error 500: Internal Server Error" appears in the console just before the app crashes. 
• Network Request: Check the attached JSON snippet from the failed API call.
• More Details: PFA for all logs: console_log.txt and dev_tools.txt files.

Step 7: Include attachments

Add visual and textual evidence that supports your claims. Attach screenshots, video recordings, log files, or any other relevant documents that can demonstrate the problem clearly. Each attachment should be named or annotated so that reviewers can easily correlate what they see with the description in the report.

Example:

• Screenshot: “Console_Error.png” showing the error message.
• Video: “ProfileUploadCrash.mp4” highlighting the exact moment the crash occurs.
• Log File: “Error_Log.txt” detailing the error codes and timestamps.

Also Read: Can’t add MP4 to Jira tickets? Here’s how to work Jira attachments.

Step 8: Check for missing details, confirm, and share

It’s best to review the complete report a couple of times before finalizing and handing off to developers or sharing with your bug tracking tools. Make any necessary revisions to eliminate ambiguities and confirm that all supporting evidence is properly referenced. Once confident that no critical details are missing, share the report with your team or directly through your bug tracking system.

Pro Tip: Create a checklist for all steps to cross-verify that nothing is overlooked or missed.

Here’s a checklist you can use before sharing a bug report with others or your bug tracking tools:

1. Make sure to reproduce a bug two to three times.
2. Verify in your bug tracking tool (using the relevant keyword) if someone else in the team has already reported the same issue.
3. Check for a similar issue in related modules.
4. Make sure to write the bug reproduction steps accurately.
5. Ensure accuracy and proper explanation while describing the issue. Writing a good summary of the issue with a polite tone works best.
6. Check if the screenshots or video recording of the issue have been properly attached.
7. Attachments and supporting documents are added to the report.
8. Check if the devtools logs, network information, and environment information have been attached.
9. The severity and priority levels have been properly marked.
10. Ensure that all relevant fields in the report have not been missed or overlooked. 
11. Proofread your bug reports twice or thrice before sharing.

Also Read: What is bug lifecycle? [Explained with steps to run]

Here’s an example of a typical bug report with key fields:

Bug report title

Title: "Add to Cart" Button Fails on Single Product Page – API Returns 500 Error and UI Event Misfires

Summary/Description

Clicking the "Add to Cart" button on the single product page leads to an error dialog instead of successfully adding the item. This failure disrupts the checkout flow. 

The issue is linked to a backend API failure, improper client-side state management, or session misconfiguration. Debugging efforts suggest possible faults in server response handling, JavaScript errors, or database transaction failures.

Also Read: How to fix “JavaScript heap out of memory” error

Visual proof of the Issue

Attached files include a screenshot (and/or a video recording) showing the error dialog and console log outputs.

Steps to reproduce the bug

1. Open the application URL: https://example-store.au
2. Select any product and open its dedicated product page (which uses the /product/{productID} endpoint).
3. Locate the "Add to Cart" button under the product image, identified by <button id="add-to-cart">Add to Cart</button>.
4. Click the "Add to Cart" button. Then, an error dialog appears, and the add to cart function fails with a message “Oops! There's a problem adding to your cart. Please try again later.”
5. Open the browser console using the shortcut F12 and check for uncaught JavaScript exceptions in the Console Tab.
6. Switch to the Network tab in devtools and inspect API request failures related to cart updates.

Expected vs. actual behavior

Expected behavior

The expected behavior is that the product should be added to the shopping cart, the UI should update dynamically, and a success toast notification should appear. 

Actual behavior

Instead, an error dialog is displayed, preventing cart updates. The API request responsible for cart additions fails with an HTTP 500 error, and the browser console logs show an uncaught JavaScript exception disrupting execution.

Bug priority

This issue is classified as Urgent, since it directly affects the ability of customers to complete purchases, directly impacting the business.

Bug severity

The severity level is Critical, as the bug prevents the primary function of adding products to the cart and disrupts the checkout flow entirely.

Environment details

• URL: https://example-store.au
• Operating System: Windows 11
• Browser: Chrome (120.0.6099.0)
• Device: Lenovo ThinkPad 15
• Network Speed: Stable connection at 100 Mbps
• Session Storage: Included in attachments for further analysis

Supporting documents and attachments

Included attachment list: 

• product-rtm-doc.pdf
• product-page.docx 
• debugging-notes.pdf
• session-storage-info.txt