Troubleshoot Issues

In this article, we will address customers common issues when performing snapshot comparisons and provide practical troubleshooting strategies to overcome them.

👉
When a user executes the application on their CI, Percy captures the snapshots (includes html, CSS and other asset files) and subsequently renders and takes screenshots in real device in Browserstack's infrastructure.

The tables presented below offer our customers valuable insights into various problems they may encounter and practical troubleshooting solutions to address them.

Debugging Scenarios for Private Content Delivery Networks [CDNs] failing to serve assets to BrowserStack

If users can identify that certain assets/resources (such as images, CSS, JSON, fonts, or any other type of assets/resources) are not being loaded by examining the Percy build or the generated build, they can consider the following case scenarios and corresponding solutions.

Problem	Solution
If certain assets are not being loaded in all browsers and those assets are not captured in your percy CI logs either.	Verify if the asset requests have been allowlisted using allowed hostnames configuration.
If certain assets are not being loaded in all browsers and those assets are not captured in your percy CI logs either and you have allowlisted the host names using allowed hostnames.	Verify if the requests in CI are timing out, and if so, increase the network-idle-timeout to capture the assets in your Percy CI.
If a snapshot includes an image that is not loaded in some of the selected browsers and you are using different resolutions for same images.	Verify all the different resolutions for the image is captured in your CI using the devicePixelRatio config.

Debugging Scenarios for Mobile Width Issues

If users can identify issues related to width of a webpage when viewed on a mobile device [mobile width], they can consider the following case scenarios and corresponding solutions.

Problem	Solution
If you notice that the entire Document Object Model [DOM] appears incorrect for mobile widths, such as when the snapshots display incorrectly in the chosen mobile browsers or appear smaller in width in selected desktop browsers.	1. If this issue occurs across all mobile widths, it is recommended to utilize the multiple DOM support feature. 2. If the issue occurred only once, it is possible that some resources did not load properly. It is recommended to retry running the test to determine if the issue persists. 3. If this issue consistently occurs for specific mobile widths or happens intermittently, it is advised to notify the Percy team for further investigation. You can raise a support ticket.
If the entire page is not scrollable when using the window scroll and if the screenshot shows a repetitive pattern throughout the page.	Add percyCSS to enable window scroll.
If the entire page is scrollable, but still a repetitive pattern is observed throughout the page.	It is advised to notify the Percy team for further investigation. You can raise a support ticket.
If some undesired changes are detected and there is a possibility to disregard them.	For flaky rendering Issue persists, check the ignore-regions configuration to resolve the problem else it is advised to notify the Percy team for further investigation. You can raise a support ticket.