Root cause analysis

Use the Root cause analysis feature to identify the cause of visual differences in your tests quickly.

The Root cause analysis feature in Percy helps you investigate visual differences effectively. If there are differences associated with a particular snapshot, root cause analysis mode displays only those differences where DOM changes are identified. If you do not see any differences, you can assume that there are no DOM differences associated with the build.

Explore Root cause analysis

Activate Root cause analysis mode to interactively explore differences within snapshots and click on specific regions to identify their root causes. Normal differences are highlighted in red color, and when this feature is turned on, a purple color bounding box appears around them. Use this feature to streamline your debugging process.

To activate Root cause analysis for a snapshot, follow these steps:

Step 1: Go to your project build review screen and click the Root cause analysis </> icon. The head image (current snapshot) transforms to display the differences interactively, with each difference region becoming clickable for detailed inspection.

Step 2: Click on a specific difference within the snapshot. This information will be displayed on the same review screen under Root cause analysis section. You can use the Diff navigator (<, >) to navigate through previous and next differences.

The review screen displays different types of differences, see the following section.

Types of differences

With Root cause analysis, you can view different types of differences, as follows:

• DOM elements
• CSS attributes
• Position related differences

DOM elements

DOM element differences occur when there are changes to the structure or attributes of elements in the DOM. This can include the addition, removal, or modification of tags or attributes.

CSS attributes

CSS attribute differences include changes in style properties, such as color, font, padding, margin, border, box shadow, opacity, background, and hover/active states.

Currently, only commonly used CSS attributes are supported.

Position related differences

Position-related differences include changes in an element’s position, size, or alignment, such as variations in width, height, aspect ratio, or spacing between elements. Misalignments within containers can also cause visual discrepancies.

These differences can significantly impact the layout and overall appearance of a page.

Visualizing changes between snapshots

The text color or background indicates the differences between the current and baseline snapshots. Green highlights values added in the current DOM, while red shows values that were removed. Identical values, such as element paths, box dimensions, or CSS rules, are not colored, emphasizing only the changes between the two snapshots.

Things to keep in mind

• This feature does not capture differences when the DOM structure does not change, even if visual differences exist. This applies to elements like:
  • Carousels: The DOM stays the same while images rotate.
  • iFrames: The outer DOM remains static, even when the content inside an iFrame updates.
• If there are two types of differences in the head image, general differences and intelli-ignore, these differences appear in different colors in Root cause analysis mode.
  • When intelli-ignore is enabled, ignored differences appear in amber color. Root cause analysis mode shows these differences only if they have an associated DOM and intelli ignore is on.
  • If the same component or element has both a normal and an intelli-ignore difference, everything is shown in red color without differentiation.
• Currently, if an ignore region is added and there is an actual DOM difference in that area, the difference appears in root cause analysis mode.
• This feature does not work when images are uploaded via Percy Upload, on Figma builds, or on snapshots.