Skip to main content

Defect Report Preparation

A well-structured bug report is crucial for efficient defect management and resolution. Several guidelines must be followed to prepare a descriptive, clear, and full report:

Title​

  • Be clear and concise; make the issue understandable from the title.
  • Stick to this structure: state the problem first, followed by when it occurs. (This brings out the importance of of the defect and makes it more clear in the reports)
    • Example: Users can't sign in, when cookies not accepted
    • NOT: When cookies not accepted, users can't sign in
  • Use common terminology for easy searchability.
  • Use bracket labels (e.g., [UI], [Performance]) to categorize.

Description​

  • Use clear, non-technical language whenever possible.
  • Add only necessary information, stay on point.
  • Ensure that anyone reading the report, regardless of their technical expertise, can understand the issue.

Scenario​

Preconditions

List any conditions or setup steps that need to be met before the defect can occur. This may include system configurations, logged-in states, or data conditions. Add only the necessary preconditions - if it doesn't matter if the condition is done or not - then don't add it

Good Example:

  • User is logged in as admin.
    • (This is essential - the defect may only occur with admin privileges.)
  • Database is set to version X.
    • (Version X introduces or exposes the defect.)
  • Feature Y is enabled in the environment.
    • (The defect is directly related to this feature being active.)

Bad Example:

  • User is logged in.
    • (If the defect is admin-specific, this is too vague and unhelpful.)
  • Database is running.
    • (This is redundant unless a specific version or configuration is relevant.)
  • Feature Y might be enabled.
    • (The "might" adds uncertainty, which is unhelpful for reproducing the defect.)
  • Browser is open.
    • (Unless the defect is browser-specific, this is an unnecessary precondition.)

Steps​

Outline the exact steps that lead to the defect. Use clear, numbered steps, separating actions performed by different users or systems. Be specific about each action to allow someone else to easily replicate the issue. List only necessary steps, stay on point. Additionally, there should be a guideline on the limit of steps in defects/test cases to keep them focused and avoid unnecessary information.

Example:

  1. Local user logs into the application.
  2. Remote user clicks the "Add Item" button.
  3. The system throws an unexpected error message.

Actual Result:

Describe the behavior that occurred when performing the steps. Be objective and detail the issue as observed. Avoid including opinions or assumptions here.

Example:

  • The "Add Item" button is unresponsive.
  • The page crashes and the application restarts automatically.

Expected Result:

Explain what the behavior should have been in an ideal scenario, based on the requirements or expected functionality. Be specific and tie it to the intended user experience.

Example:

  • The "Add Item" button should redirect the user to the next page.
  • The application should not crash during use.

Affected Test Cases

Provide links to the test cases that are impacted by the defect. Mention if new test cases are required for validating this defect or covering it in future releases.

Example:

  • Test Case TC_1234 needs to be refactored to check for button response.
  • A new test case may need to be created to validate this button functionality.

Notes/Additional information:

Include any additional information that might be helpful for understanding the defect. This can include observations like whether the issue is reproducible in previous versions, if it’s a regression, or if there are any workarounds available.

Example:

  • This issue appears only in version 2.0 and is not present in version 1.9.
  • Issue occurs intermittently during peak traffic times.

Environment:

Specify the environment where the defect was found. This may include the operating system, browser, application version, or any other relevant environmental factors.

Example:

  • OS: Windows 10
  • Browser: Chrome 89
  • Application Version: 2.1.5

Evidence Guidelines for Bug Reports:​

  • Visual Evidence: Always attach relevant screenshots or videos of the defect. Highlight the issue clearly using built-in tools (avoid freehand drawings). Keep videos brief and focused.
  • Logs: Attach logs related to the issue. Ensure that a new session or call is initiated before downloading logs to avoid overlap with unrelated actions.
  • Call ID: If logs are attached, include the corresponding Call ID to link the log to the defect.

Best Practices for gathering evidences

  • Organize Files: Save recordings and screenshots in a structured folder system with clear labels, such as project names, dates, or ticket IDs, to ensure quick and easy retrieval.
  • Meaningful Naming: Assign descriptive file names to evidence files, such as "Login_Error_Step3.mp4" or "UI_Misalignment_2024-01-15.png". This helps identify the file’s content at a glance and avoids confusion.
  • Highlight Issues: Use annotation tools to mark specific areas of concern in screenshots or recordings. Clearly highlighting the issue helps reviewers quickly understand the problem without extra explanations.
  • Compress Large Files: Optimize file sizes before sharing to ensure smooth uploads and downloads. Use compression tools to reduce file size while maintaining clarity and quality.
  • Standardize Evidence Submission: Follow consistent formats and naming conventions for all evidence files to ensure uniformity and professionalism in defect reports.

Possible tools for gathering evidence​

Selecting the right tool for screen recordings and screenshots ensures efficiency and clarity when documenting and sharing issues across various platforms. Below are options tailored to different operating systems:

  • Windows: Windows users can utilize built-in tools like the Snipping Tool or Game Bar for quick screenshots and screen recordings. For advanced features, such as annotating screenshots or capturing specific application windows, third-party applications provide enhanced functionality. Consider tools that allow recording audio alongside screen activity for a more comprehensive demonstration.
  • MacOS: MacOS offers native tools like Shift + Command + 5, enabling users to capture screenshots, record the screen, and save the output in customizable formats. For more specialized needs, such as editing or annotating evidence, third-party tools can provide additional features that improve usability and productivity.
  • iOS: iOS devices have a built-in screen recording feature accessible from the Control Center. Users can easily record app interactions and add voice commentary to recordings. Screenshots can be edited immediately with markup tools to highlight issues. Third-party apps are also available for users who need advanced editing or cloud-sharing capabilities.
  • Android: Most modern Android devices have built-in screen recording tools, often accessible via the notification panel. Screenshots can be quickly annotated with built-in or downloadable apps. For older devices or additional features like long-scroll capture, third-party apps can be used to enhance evidence collection and sharing.

Commonly used fields in bug reports​

Usually, there are commonly used fields in various defect management tools, and here is a list with brief explanation of how to fill them out:

  • Labels: Categorizes or tags the defect with relevant keywords for easier searching and grouping (e.g., "UI", "performance").
  • Priority: Indicates the urgency of fixing the defect, helping prioritize based on its impact (e.g., High, Medium, Low).
  • Issue Occurrence Rate: Describes how often the defect occurs (e.g., "Always", "Intermittent", "Rarely"), aiding in prioritization.
  • Epic Link: Connects the defect to a larger feature or epic, providing context for the broader scope of the project.
  • Sprint: Refers to the sprint or iteration in which the defect was found or is being worked on, tracking progress in Agile projects.
  • Device Information: Includes details about the device or platform (e.g., type, model, OS version) where the defect was found, helping diagnose device-specific issues.
  • Assignee: Identifies the person or team responsible for resolving the defect, ensuring accountability.
  • Linked Issues: Shows relationships to other defects, tasks, or issues, helping track dependencies and related items.
  • Fix version: Indicates the version in which the issue was resolved.