Troubleshoot Common Issues
Learn how to debug commonly seen issues
On this page, we will address common issues when performing snapshot comparisons and provide practical troubleshooting strategies to overcome them.
IMPORTANT
When you execute the application on your CI, Percy captures the snapshots (includes html, CSS and other asset files) and subsequently renders and takes screenshots in real device on BrowserStack’s infrastructure.
Debugging Scenarios for Private Content Delivery Networks [CDNs] failing to serve assets to BrowserStack
If you 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, you 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 you identify issues related to width of a webpage when viewed on a mobile device [mobile width], you 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. |
Smart Debugging: Flakiness
If you identify issues with flakiness, consider the following case scenarios and possible solutions.
| Problem | Solution |
|---|---|
| Incorrect diffs in page for certain browsers only or Incorrect diffs in page. | 1. Add any failed network logs to allowed host names in Percy. 2. You can modify how Percy handles your DOM by passing a domTransformation function to avoid any issues. Learn more. 3. You can instruct Percy to handle specific parts of your page differently using PercyCSS. |
Smart Debugging: Screenshot Issue
If you identify issues with screenshots, consider the following case scenarios and possible solutions:
| Problem | Solution |
|---|---|
| The full-page screenshot displays incorrect elements. | 1. Scroll to the correct location on the page in your driver and take a screenshot. 2. You can instruct Percy to hide the element using PercyCSS. |
| Full Page Screenshot is not captured. | If internal elements are scrollable, make them fully scrollable using PercyCSS. 2. If a scoped screenshot does not capture the complete element, use the scroll-scope: true configuration. Learn more.
|
| Some elements are not rendering. | Percy disables animation by default. If your animated element is not rendered, use PercyCSS for the same. |
| Responsive pages were not correctly captured for different widths. | Use the defer upload functionality to load DOMs on the specific device instead of reusing the DOM from your CI. Learn more. |
Smart Debugging: Page Load Issue
If you identify issues with page loading, consider the following case scenarios and possible solutions:
| Problem | Solution |
|---|---|
| The Page loads partially. | You can instruct Percy to handle specific parts of your page differently using PercyCSS. |
| Element not loaded in Percy, but it loads in the browser. | 1. The element may take longer to load, causing the snapshot to be captured before it’s fully rendered. 2. For script-based snapshots, ensure the element is loaded before capturing. If using the Percy command for example npx percy snapshot <snapshot_config>, you can wait for elements or set specific durations using waitForSelector or waitForTimeout in your configuration. Learn more. 3. If you encounter a network idle timeout while capturing responsive assets, disable this by setting the environment variable PERCY_DO_NOT_CAPTURE_RESPONSE_ASSETS=true. This helps when different assets are served for various screen widths. |
| Other asset are not loading (font/css). | 1. Add any failed network logs to the allowed host names in Percy. 2. Address specific network errors that you might see in your logs or in the network errors tab. 3. If assets are lazily loaded, make sure to scroll to the bottom of the website before taking a snapshot. Learn more. 4. If assets are in srcset, use captureSrcset: true in the configuration file. Learn more. 5. If assets are behind authorization, use the authorization config. Learn more. |
| Responsive element loading failed or is incorrect. | 1. You can instruct Percy to handle specific parts of your page differently using PercyCSS. 2. You can modify your browser’s DOM to ensure that it appears correct in Percy. Learn more. |
| Invalid DOM. | DOM Transformation: You can modify your browser’s DOM to ensure that it appears correct in Percy. Learn more. |
| The page captured is blank or in a loading state. | 1. Make sure before calling percySnapshot page is loaded completely. 2. If enable-javascript: true then try using enable-javascript: false. Learn more. 3. Use waitForSelector and waitForTimeout configuration. Learn more.
|
| Pages timed out while rendering in Percy. | If enable-javascript is true, set it to false. Learn more.
|
Smart Debugging: Desktop vs Mobile Screenshot issues
If you identify issues with Desktop vs Mobile screenshot, consider the following case scenarios and possible solutions:
| Problem | Solution |
|---|---|
| The screenshot does not look correct on mobile or desktop, due to different assets. | Use the defer upload functionality to load DOMs on the specific device instead of reusing the DOM from your CI. Learn more. |
| Invalid DOM for one device/browser: The screenshot on mobile looks like the desktop version or vice versa. | 1. You can instruct Percy to handle specific parts of your page differently using PercyCSS. 2. You can modify your browser’s DOM to ensure that it appears correct in Percy. Learn more. 3. Use the defer upload functionality to load DOMs on the specific device instead of reusing the DOM from your CI. Learn more. |
Smart Debugging: Authorisation issues
If you identify authorisation issues, consider the following case scenarios and possible solutions:
| Problem | Solution |
|---|---|
| The Page requires cookie based authorization, which has not been completed. | Pass the authorization cookie in the network request. |
| The Page requires basic authorization, which has not been completed. | Pass the authorization header in the network request. |
Smart Debugging: Snapshots Missing or Failed
If you identify issues like Snapshots Missing or Failed, consider the following case scenarios and possible solutions:
| Problem | Solution |
|---|---|
| Some snapshots are missing. | Try reducing the concurrency to 1. |
| Active requests are pending in the CI logs. | Try increasing PERCY_NETWORK_IDLE_TIMEOUT. |
| Page loading failed in the CI environment. | Try increasing PERCY_PAGE_LOAD_TIMEOUT. |
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Is this page helping you?
Yes
No
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!
