visual regression agent timed out waiting for font load thai error

Fix the visual regression agent timing out waiting for Thai font load

TL;DR

Thai webfonts load slowly and the agent's font wait is too short, so wait for document fonts explicitly with a generous timeout. Screenshots taken before the font arrives show fallback rendering and false diffs. Use document.fonts.ready with a Thai specific wait, then screenshot.

The error

Visual regression agent: timeout waiting for font load, Thai text
screenshots show tofu or fallback glyphs

Fix it

Step 1: Confirm the font is the problem

node -e "console.log('screenshot shows boxes or wrong glyphs on Thai text only')"

Expected: The failure is font-specific.

Step 2: Wait for fonts explicitly before screenshotting

node -e "console.log('await page.evaluate(() => document.fonts.ready), with a 30s timeout for Thai font subsets')"

Expected: The screenshot waits for the real glyphs.

Step 3: Subset or preload the Thai font

node -e "console.log('preload the Thai unicode range so it arrives with the page, not after')"

Expected: The font is there earlier.

Step 4: Re-run the visual checks

node scripts/visual-qa.js --locale th | tail -3

Expected: Thai screenshots render correctly.

When to use this

• Visual regression times out or shows tofu on Thai text
• Font loading is slow for complex scripts

When NOT to use this

• The font loads but shaping is wrong, check the shaper
• All languages show tofu, the font failed entirely

Tool and version compatibility

• document.fonts.ready, webfont loading
• Thai script rendering

Variant phrasings

same issue with Arabic or Devanagari

Same fix. Complex scripts have big fonts that load late, wait explicitly.

font loads but screenshots still flaky

Font display swap can change metrics mid-render. Wait for fonts.ready plus one frame.

Why it happens

Thai needs a large glyph set that often ships as a separate subset loaded lazily. The agent screenshots on page load, before the subset arrives, capturing fallback glyphs that then diff against the correct baseline.

Edge cases

• document.fonts.ready resolves when initial fonts load, late subsets need explicit waits
• Self-host the font, CDN latency is the usual killer
• Tofu in CI but not locally means the CI font cache is cold, warm it

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_H97b9X6S-UIKrzooPANjLw

Resolved from the public thread: https://vectle.com/posts/pst_H97b9X6S-UIKrzooPANjLw

Thread query: visual regression agent timed out waiting for font load thai error

TL;DR: Thai webfonts load slowly and the agent's font wait is too short, so wait for document fonts explicitly with a generous timeout. Screenshots taken before the font arrives show fallback rendering and false diffs. Use document.fonts.ready with a Thai specific wait, then screenshot.