How to Report Bugs When Visual Testing

How to Report Bugs During Visual Regression Testing

Did you know that over 60% of UI defects reported in production are visual?

When visual bugs encompass the majority of the last-minute fixes, it is essential to understand how you can scale bug detection and capture efficiently.

I’ve accumulated some measures that I have opted through over the years which have helped me report bugs faster through automated visual testing tools.

What Are Visual Bugs and What Are Its Types?

Visual bugs are unintended changes or defects in the user interface that alter the appearance of an application without necessarily breaking its functionality.

The feature may still work as expected, but the UI looks incorrect, inconsistent, or incomplete to the user.

These bugs affect layout, styling, spacing, images, colors, or responsiveness. Unlike functional defects, visual bugs often go unnoticed in traditional automated tests because the underlying logic continues to pass.

Below are the 8 most common types of visual bugs teams encounter during visual regression testing:

1. Layout and Alignment Issues

Layout bugs occur when elements overlap, shift unexpectedly, or appear misaligned. A button may drop below a form field, or cards in a grid may lose structure after a CSS update.

Even minor style changes can disturb page structure. These issues are highly visible to users and often impact usability.

2. Typography Errors

Typography bugs include incorrect fonts, inconsistent sizes, or text overflowing its container. Headings may appear lighter than intended, or paragraph text may wrap improperly.

These issues often result from missing font files or untested responsive styles. They affect readability and overall design consistency.

3. Responsive Design Failures

Responsive bugs appear when the layout breaks across different screen sizes. A design that works on desktop may stack incorrectly or hide elements on mobile.

Improper media queries or missing breakpoints usually cause these failures. Testing across multiple viewports helps surface them early.

4. Color and Contrast Issues

Color bugs involve incorrect brand colors, broken theme variables, or low contrast between text and background. Even subtle color shifts can impact brand perception.

Poor contrast also affects accessibility compliance. Visual testing helps detect unintended style overrides.

5. Image and Icon Problems

Images may fail to load, appear stretched, or render in low resolution. Icons can disappear due to path errors or font library misconfigurations.

Asset optimization or CDN updates often introduce these issues. Visual comparisons make them immediately noticeable.

6. Cross-Browser or Device Malfunctions

A layout that looks correct in one browser may render differently in another. Differences in rendering engines can create spacing variations or broken components.

Device-specific inconsistencies also surface due to scaling and viewport handling. Cross-browser visual regression testing helps catch these variations.

7. Spacing Issues

Spacing bugs occur when padding or margins become inconsistent. Sections may look cramped or overly spaced after minor CSS changes.

Although subtle, spacing inconsistencies reduce perceived design quality. Visual regression tools are effective at detecting these small shifts.

8. Invisible or Hidden Elements

Hidden element bugs happen when UI components are present in the code but not visible to users. Incorrect CSS properties such as display: none or overflow clipping can cause this.

These issues are risky because functionality exists, but users cannot access it. Visual testing surfaces such problems before release.

What is Bug Detection Under Visual Regression Testing?

Bug detection under visual regression testing refers to the automated process of identifying unintended UI changes by comparing the current version of a page against a previously approved baseline. Instead of checking logic or functionality, this process focuses purely on visual differences.

When a developer pushes new code, the visual regression tool captures fresh snapshots of the UI. These snapshots are then compared pixel-by-pixel or through DOM-based rendering against the baseline images. Any difference is flagged as a potential visual bug.

The key advantage is automation at scale. Manual UI reviews are subjective and inconsistent, especially across browsers and devices. Visual regression testing standardizes detection by highlighting exact areas where the UI has changed.

Modern tools such as BrowserStack Percy use DOM snapshotting and controlled rendering environments to reduce noise caused by local machine differences. Instead of relying only on pixel comparison, Percy reconstructs the page and identifies meaningful visual changes.

How to Report Bugs During Visual Regression Testing

Reporting visual bugs works best when you treat every detected diff as a reviewable change, not an immediate defect. The goal is to capture clear evidence (what changed, where it changed, and why it matters), then route it to the right place in your workflow.

A repeatable process also keeps teams from debating screenshots in comments or chasing “works on my machine” issues.

Below is a practical, step-by-step flow using Cypress and Percy, with examples you can adapt to your stack:

Step 1: Add stable visual checkpoints in your tests

Pick pages or components where visual stability matters, then add snapshots after the UI is fully ready. Keep snapshots scoped and meaningful rather than capturing everything on every route.

// cypress/e2e/checkout.cy.js

describe('Checkout UI', () => {

  it('captures checkout layout', () => {

    cy.visit('/checkout');



    // Wait for critical UI to be ready (avoid fixed waits)

    cy.get('[data-testid="checkout-summary"]').should('be.visible');



    cy.percySnapshot('Checkout - Summary');

  });

});

If your UI has animation or late-loading elements, wait on a deterministic signal, such as a loaded state, a visible selector, or network completion.

Step 2: Run visual tests in CI so every change produces a diff

Percy works best when snapshots are generated on every pull request. That gives reviewers a consistent place to confirm whether visual changes are expected.

# Example CI command

npx percy exec -- cypress run

This runs Cypress as usual, then Percy collects snapshots and publishes comparisons to the Percy dashboard for review.

Step 3: Review the diff and confirm it is a real bug

When a build shows visual changes, open the comparison view and check the highlighted regions. Confirm whether the change is unintended (a regression) or an expected update that should become the new baseline.

A simple rule helps: if the UI change was not mentioned in the PR description, treat it as suspicious until proven otherwise.

Step 4: Capture bug-ready context from the visual diff

A strong visual bug report includes what changed, where it changed, and the conditions under which it appears. Percy diffs already provide before/after views and the changed regions, so the report becomes much easier to write.

Use this checklist:

• Page/component name and snapshot label
• Expected vs actual behavior (what’s wrong visually)
• Browser/device context (desktop, mobile web viewport, cross-browser)
• Link to the Percy build or diff (as source of truth)

Step 5: Create the bug ticket with a consistent template

If your team files bugs in Jira, GitHub Issues, or similar tools, a consistent structure keeps triage fast. This example is intentionally short but complete.

Example visual bug report

• Title: Checkout summary overlaps payment button on mobile
• Where: /checkout, snapshot “Checkout – Summary”
• Expected: Summary panel stays within container, button remains visible
• Actual: Panel overlaps primary CTA after recent CSS change
• Evidence: Percy diff link + screenshot comparison
• Notes: Reproduces at 390×844 viewport (mobile web)

Step 6: Prevent repeat bugs with targeted snapshots and approvals

Once fixed, keep the snapshot in place so the same regression is caught automatically next time. If the change is intentional, approve the new baseline so future diffs stay meaningful.

This approach keeps visual regression testing focused on catching real issues, while making bug reporting fast enough to fit naturally into code review.

Merging Percy With Slack for Reporting Visual Bugs

Visual regression testing becomes truly effective when detected changes are instantly visible to the team. Instead of manually checking dashboards, Percy integrates with Slack to automatically notify teams about visual changes in pull requests and builds. This reduces the gap between detection and action.

Slack notifications ensure that visual bugs are surfaced in real time, directly within the communication channel where developers already collaborate.

Step 1: Enable Slack Integration in Percy

Navigate to your Percy project settings and select the Slack integration option. Authorize Percy to connect with your Slack workspace and choose the channel where notifications should appear.

You can configure notifications for build status updates, changes detected, approvals, or failures. Keeping notifications focused ensures the channel stays actionable.

Step 2: Trigger Visual Tests Through CI

Once integrated, every time a pull request triggers visual regression tests, Percy analyzes the snapshots and compares them against the baseline.

npx percy exec -- cypress run

After the build completes, Percy automatically sends a Slack message with:

• Build status
• Number of changed snapshots
• Direct link to review visual diffs

Step 3: Review and Confirm the Visual Bug

Clicking the Percy link in Slack opens a side-by-side comparison view. Reviewers can inspect highlighted differences and decide whether the change is expected or a regression.

If the change is unintended, it should be reported as a visual bug. If intentional, the new baseline can be approved directly within Percy.

Step 4: Convert Slack Alerts Into Actionable Bug Reports

When a regression is confirmed, create a bug ticket in your tracking system and attach:

• Percy build link
• Snapshot name
• Expected vs actual visual behavior
• Browser or device context

The Slack message acts as the entry point, while Percy serves as the evidence source. This structured workflow eliminates ambiguous screenshots and reduces back-and-forth communication.

Why This Workflow Matters

Manual visual reviews are inconsistent and often delayed. Integrating Percy with Slack brings automated visual bug detection into daily development conversations.

Teams no longer wait for QA cycles to discover UI issues. Visual regressions are detected, reviewed, and reported as part of the pull request workflow, which shortens feedback loops and improves release confidence.

Why Use Percy for Visual Regression Testing

Percy is an AI-powered visual regression testing tool that automates UI comparison across browsers and devices. It captures DOM-based snapshots, re-renders them in a consistent environment, and highlights visual differences against approved baselines.

Percy integrates with over 50 automation frameworks including Cypress, Selenium, Puppeteer, and WebdriverIO, which makes adoption seamless within existing pipelines. It connects directly with CI/CD workflows, associates visual changes with pull requests, and supports real-time Slack notifications for faster collaboration.

For responsive and mobile experiences, Percy supports mobile web visual testing, while App Percy extends similar capabilities to native and hybrid mobile applications.

This is why many teams choose to go with Percy:

Percy Guarantees 3× Faster UI Reviews

Review and approve hundreds of visual changes on the go, leaping beyond manual reviews.

Try Percy

Conclusion

Visual bugs rarely break functionality, but they directly impact user trust and product quality. Relying only on manual reviews or functional tests leaves gaps that allow UI regressions to reach production. Visual regression testing closes that gap by automatically detecting unintended design changes before release.

With tools like Percy, teams can standardize visual bug detection, streamline reporting through CI and Slack, and maintain consistency across browsers and devices. This structured approach transforms visual quality from a reactive concern into a proactive safeguard within the development lifecycle.