If a page uses the right font in your test browser but Percy shows a fallback, check the font request and Percy’s asset-discovery errors before changing CSS. Percy captures the DOM in the test browser, then discovers assets and renders the snapshot in Percy infrastructure; a font can fail at either stage. Fix access or readiness first, and tune discovery timing only when the build shows that a font request arrives late.
First identify where the font changes
Compare the page immediately before the Percy snapshot with the rendered Percy result. If the test browser already shows a fallback, investigate application loading and test readiness. If the font looks correct before capture but not in Percy, inspect the Percy build’s network and asset errors: the later discovery and rendering stages may not have retrieved or applied the font.
As an Amazon Associate I earn from qualifying purchases.
Percy’s documented workflow separates DOM capture from asset discovery and rendering. A CSS rule that references a font is not proof that Percy successfully fetched the font file. BrowserStack’s Percy SDK and screenshot capture workflow describes these stages.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsCheck whether Percy can fetch the font
- In the Percy build, look for the font URL and related network or asset errors. Check whether the request failed, was blocked, or returned an unexpected response.
- Confirm the font host is available to Percy’s asset discovery. If the build reports a failed asset host, add that host to the allowed hostnames as appropriate and run the snapshot again.
- If the font is protected, investigate the authentication configuration for that asset. Allowlisting a host alone will not fix an authorization failure.
- Recheck the Percy-rendered snapshot after the access issue is resolved.
BrowserStack’s Percy troubleshooting guide calls out failed font and CSS resources, host allowlisting, slow elements, and lazy-loaded assets. Follow the specific error rather than assuming the problem is simply that the test needs a longer sleep.
#1 Best Overall
Wait for the page’s real ready state
Take the snapshot only after the application has reached the state the test intends to capture. Prefer an application-specific signal—such as a visible component or a completed state transition—to an arbitrary delay. Percy’s troubleshooting guidance documents waitForSelector and waitForTimeout for CLI configuration; use a timeout when observed loading behavior justifies it, not as a substitute for diagnosing a failed request. See the Percy snapshot command configuration.
In a scripted browser test, you can also check that the required font is ready in the test browser before calling percySnapshot, if your browser and test setup support that check. Treat it as a precondition for capturing the DOM, not a guarantee that Percy’s later asset discovery will retrieve the font. Confirm the result in the Percy build.
Rank #2
The snapshot options documentation does not list a universal dedicated “wait for fonts” option. Tie readiness checks to your application and verify the rendered result instead of relying on an undocumented setting.
Increase asset-discovery time only when the request is late
Percy’s workflow documentation says asset discovery defaults to waiting for 100 ms with no new network requests. If build or network evidence shows the font request starts too late for that window, increase the relevant network-idle-timeout in Percy configuration or CLI use, then rerun the build. The documented default is from BrowserStack’s Percy SDK and screenshot capture workflow.
A longer idle window can help with a late request; it cannot make a blocked, unauthorized, or missing font accessible. Avoid applying a large blanket delay when the build already shows a request failure.
Trigger lazy-loaded assets before capture
If the font or its stylesheet is requested only after scrolling or interaction, make that behavior happen before the snapshot:
Rank #4
- Used Book in Good Condition
- Browser-driven tests: perform the relevant interaction or scroll in the test browser before asking Percy to snapshot.
- CLI snapshots: use the documented
beforeSnapshottechnique to scroll the asset-discovery browser into the relevant area. The CLI asset-discovery browser does not scroll by itself.
Follow BrowserStack’s guide to capturing lazy-loaded elements in Percy snapshots for the CLI setup. Trigger the actual lazy-loading condition rather than masking the missing font with a visual override.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Use Percy-specific CSS only for an intentional rendering change
Percy-specific CSS is applied in Percy’s rendering environment and can adjust the appearance being tested. It is suitable when a deliberately different Percy rendering state is the test condition. It is not a repair for a font file Percy cannot retrieve. For a UI that is meant to use a particular font, fix delivery, access, or discovery first; forcing a fallback can conceal a genuine regression.
Best Value
See BrowserStack’s documentation for Percy-specific CSS for the available configuration.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choose the fix by the evidence
| Evidence | Likely stage | Best next action | Risk to watch |
|---|---|---|---|
| The page already uses a fallback just before snapshot | Application or test-browser readiness | Fix the app’s font loading or wait for its actual ready condition | A Percy-only override may hide an application defect |
| The page looks correct before snapshot; Percy reports a failed font request or host | Asset discovery access | Resolve the request error, host allowlisting, or required authentication | A longer timeout will not fix an inaccessible asset |
| The request appears late in network evidence | Asset-discovery timing | Increase the relevant network-idle timeout and verify the build | Unnecessary waits slow snapshots without fixing other failures |
| The asset appears only after scroll or interaction | Lazy loading during discovery | Trigger the behavior in the browser test or use CLI beforeSnapshot |
Changing the font style does not load the deferred asset |
| The font is intentionally different in Percy | Percy renderer | Use Percy-specific CSS for that deliberate test condition | Do not use it to conceal a broken font request |
Or skip the browser setup
For a standalone website screenshot, ScreenshotNeo provides a single-request API. This does not replace Percy’s visual-testing workflow, but it can capture a page without setting up a browser script:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers say which page verdict and billing status applied. An MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.
Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Does Percy have a universal wait-for-fonts snapshot option?
The documented snapshot options do not list a universal dedicated wait-for-fonts setting. Use an application-specific readiness check and verify the Percy build.
Will increasing network-idle-timeout fix a blocked font?
No. It can help when evidence shows a request arrives late; a blocked or unauthorized request needs its access problem resolved.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
