Smart debug for asset capture failures

Learn how smart debug helps you identify and resolve asset capture failures in Percy snapshots.

Percy’s smart debugging feature helps you quickly identify and resolve asset capture failures in your visual testing workflow. When assets fail to load or capture during snapshot creation, smart debugging provides detailed insights and actionable recommendations to help you fix the issues efficiently.

What are asset capture failures?

Asset capture failures occur when Percy cannot successfully capture resources required to render your snapshots accurately. These resources include:

• Images and icons
• Stylesheets (CSS files)
• JavaScript files
• Fonts
• Media files (videos, audio)
• Third-party resources (CDN assets, external APIs)

Asset capture failures can result in incomplete or incorrect visual snapshots, leading to false positives in your visual testing results.

Access smart debugging

To access smart debugging features for asset capture failures:

1. Navigate to the Percy dashboard.
2. Select your project from the projects list.
3. Open the build that contains snapshots with asset capture failures.
4. Click the thumbnail in the build toolbar.

Best practices

Follow these best practices to minimize asset capture failures:

• Configure allowed hostnames: Proactively add all external domains that host assets for your application
• Set appropriate timeouts: Configure network timeouts based on your application’s typical load times
• Use authentication properly: Configure authentication credentials for protected resources
• Validate asset URLs: Ensure all asset URLs are absolute and use the correct protocol (http or https)
• Monitor build logs: Regularly review build logs and network activity to catch issues early
• Test locally: Use the --debug flag when running Percy locally to troubleshoot asset discovery without consuming screenshots:

percy exec --debug -- your-test-command

For more information, see Debugging SDKs.

Related topics

• View Network logs
• Percy SDK workflow
• Troubleshoot common issues
• Percy configuration options
• Assets not captured