Font rendering differences in visual tests

Font rendering is surprisingly complex. The same font file can produce visually different output depending on the operating system, browser, display, and configuration.

These differences are subtle individually but compound across a page. A screenshot from macOS compared to Linux CI will show differences on nearly every text element.

The goal is to ensure your screenshots are captured in an identical environment every time—regardless of who runs them or where.

The most reliable approach is to run visual tests inside a Docker container. This gives you complete control over the OS, font packages, and rendering configuration.

FROM mcr.microsoft.com/playwright:v1.40.0-jammy

# Install fonts your app uses
RUN apt-get update && apt-get install -y \
    fonts-liberation \
    fonts-noto-color-emoji \
    && rm -rf /var/lib/apt/lists/*

# Optional: install custom fonts
COPY ./fonts /usr/local/share/fonts
RUN fc-cache -fv

See Docker setup for deterministic rendering for a complete configuration guide.

Web fonts are bundled with your application, ensuring the same font files are used everywhere. But you must wait for them to load before capturing screenshots.

In Playwright, wait for fonts explicitly:

// Wait for all fonts to load
await page.evaluate(() => document.fonts.ready);

// Or check specific fonts
await page.evaluate(async () => {
  await document.fonts.load('16px "Inter"');
});

Font loading can be slow on first page load. If you're seeing fallback fonts in screenshots, increase your wait time or add an explicit font load check.

CSS can help normalise font rendering across platforms. Force antialiased rendering to reduce subpixel variance:

/* Add to your test environment CSS */
* {
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-rendering: geometricPrecision;
}

This reduces but doesn't eliminate differences. Different operating systems still interpret these properties differently. It's most effective when combined with a pinned Docker environment.

When you see unexpected font diffs, here's how to identify the root cause:

• Check computed styles: Use DevTools to verify which font is actually rendering. The computed font-family shows the resolved font, including fallbacks.
• Compare font metrics: Capture the same text in both environments and overlay them. Font rendering differences manifest as slightly different character widths and heights.
• Verify font loading: Check document.fonts.status and document.fonts.check() for specific fonts. FOUT (flash of unstyled text) suggests incomplete font loading.
• Isolate the variable: Run the same test in Docker locally and in CI. If they match, the issue is local environment. If they differ, check Docker image consistency.