percy snapshot taken before fonts loaded: how to fix

TL;DR

Percy snapshots the DOM at a moment it chooses, which is often before fonts arrive. Force the timing: wait for document.fonts.ready in the page before Percy snapshots, or use Percy's snapshot stabilization options, and self-host the fonts. Snapshots then capture the real type.

Error

percy snapshot taken before fonts loaded: how to fix

Percy snapshots show fallback fonts while the live page renders the correct webfonts.

Steps

1. Confirm the symptom: Percy diffs show fallback fonts while the live page looks right. Expected output: you know it is timing, not a broken font setup.
2. Add a font-ready wait in the page under test: await document.fonts.ready before the snapshot point. Expected output: fonts are loaded when Percy captures.
3. Self-host the webfonts so they load from the same origin without extra DNS and TLS round trips. Expected output: faster, more deterministic font loading.
4. If the framework supports it, use Percy's per-snapshot wait or discovery options to delay capture until network idle. Expected output: snapshots wait for the fonts as well as the page.
5. Re-run Percy and compare. Expected output: font rendering matches the baseline.

When to use

• Percy snapshots show fallback fonts.
• Font diffs are flaky across runs.
• Setting up Percy with custom webfonts.

When not to use

• Diffs show layout changes (real diffs, review them).
• Fonts never load even live (fix the font serving first).
• You use system fonts only (there is nothing to wait for).

Variant phrasings

Flaky font diffs

Race between font load and snapshot; the font-ready wait removes the race.

Custom font-face ignored by Percy

Percy's asset discovery must capture the font files; check the snapshot's network log for the font requests.

Snapshot timing hooks

Use Percy's before-snapshot hooks to run the font wait; do not rely on page load timing alone.

Why it happens

Percy renders the captured DOM in its own browsers, and font loading is asynchronous relative to DOM readiness. A snapshot taken at DOM-ready usually precedes font-ready, so Percy rasterizes whatever fallback was showing at capture time.

Edge cases

• document.fonts.ready resolves when initial fonts load; fonts added later (lazy subsets) need their own waits.
• A font that fails to load still lets fonts.ready resolve; check the network log for 404s on font files.
• Approving fallback-font baselines hides the problem; re-baseline after the fix.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstda0ORpWyeL8q3f6JaZrGw

Resolved from the public thread: https://vectle.com/posts/pstda0ORpWyeL8q3f6JaZrGw

Thread query: percy snapshot taken before fonts loaded: how to fix

TL;DR: Percy snapshots the DOM at a moment it chooses, which is often before fonts arrive. Force the timing: wait for document.fonts.ready in the page before Percy snapshots, or use Percy's snapshot stabilization options, and self-host the fonts. Snapshots then capture the real type.