testingmapsfonts

Testing Map Label Rendering: Automated Tests for Multiscript Cartography

UUnknown

2026-03-10

10 min read

Practical test suite for validating Latin, CJK, Arabic, and Devanagari map labels with shaping, bidi, and font fallback checks.

Hook: Why your map labels still break in production — and how to prove it

Mapping teams building global apps face recurring pain: labels that render fine on one device but break in another, Arabic text that loses shaping, Devanagari conjuncts rendered as separated glyphs, or CJK names that fall back to an ugly system font. If you can't reliably test those cases in CI, you will ship regressions and support tickets. This article gives a practical, production-ready test suite and code snippets to validate Latin, CJK, Arabic, and Devanagari labels with bidi, shaping, font fallback, grapheme cluster handling, and accessibility checks — built for mapping teams competing with large map providers in 2026.

Summary: What you'll get

A repeatable test matrix for multiscript map labels
Browser-based rendering tests (Playwright) with pixel-compare strategy
Programmatic shaping checks via HarfBuzz (WASM) and ICU/Intl APIs
Font fallback detection and deterministic fallbacks for CI
Accessibility checks: screen-reader names, grapheme clusters, and text selection
CI integration notes and tolerance strategies for visual diffs

Why this matters in 2026

In late 2025 and early 2026 we saw two important trends escalate: wider adoption of WASM-based shaping engines (HarfBuzz) for server and client consistency, and improved browser-level font-fallback APIs that make testing feasible. At the same time, variable fonts and color emoji updates increased the surface area of rendering differences. For mapping teams, these trends mean both opportunity (more deterministic shaping) and risk (more asset variation). A focused test suite closes the loop between typography, shaping engines, and raster/OS font stacks.

Design goals for a map-label test suite

Deterministic — tests should run the same in CI and locally.
Multi-layer — verify text shaping, glyph selection, and raster output.
Actionable — failures point to shaping, font availability, or CSS/label engine bugs.
Lightweight — integrate into existing Playwright/Jest CI pipelines.
Accessible — test screen-reader names and grapheme cluster boundaries.

Core test matrix (what to test)

Organize your tests by label type and failure mode. Each row should be a test fixture used in both shaping and rendering checks.

Latin: accented characters, ligatures, RTL/LTR mixing (e.g., "St. John's — شارع")
CJK: Han variants, full-width punctuation, ideographic spaces, mixed Latin/CJK labels
Arabic: contextual shaping across joins, diacritics, Arabic+Latin mixing (bidi runs)
Devanagari: complex conjuncts, virama sequences, combining marks
Emoji/fallback: ZWJ sequences, emoji + text mixing, regional indicator pairs (flags)

Example fixtures

// fixtures/labels.json
[
  {"id":"lat-accent","text":"São Paulo – Av. Paulista"},
  {"id":"cjk-mixed","text":"北京市 Jing'an 区"},
  {"id":"arab-shape","text":"شارع النور‎"},
  {"id":"dev-conj","text":"संस्कृत्"},
  {"id":"bidi-mix","text":"Hotel ABC - مطار‎"},
  {"id":"emoji-zwj","text":"🏳️‍🌈 Rainbow Ave"}
]

Approach A — Browser-based rendering and pixel comparisons

Use Playwright (or Puppeteer) to render labels into a fixed DOM canvas and capture a PNG. Compare against a baseline image using a perceptual diff (SSIM) with a small tolerance. This detects font fallback, missing glyphs (tofu), and layout shifts from shaping differences.

Key implementation details

Render labels at a fixed DPI and device scale factor in headless Chromium/Firefox to reduce variability.
Use deterministic CSS: exact font stacks, font-size in px, and text-rendering settings.
Simulate missing fonts in CI by not loading your proprietary fonts; rely on web fonts where possible.
Store per-language baseline images and review diffs in PRs.

Playwright sample

// tests/label-render.spec.js
const { test, expect } = require('@playwright/test');
const fs = require('fs');

test.describe('label rendering', () => {
  test.use({ viewport: { width: 800, height: 200 }, deviceScaleFactor: 1 });

  const fixtures = JSON.parse(fs.readFileSync('./fixtures/labels.json'));

  for (const f of fixtures) {
    test(f.id, async ({ page }) => {
      await page.goto('about:blank');
      await page.setContent(`
        ${f.text}
      `);

      const label = await page.$('#label');
      const image = await label.screenshot();
      expect(image).toMatchSnapshot(`${f.id}.png`, { threshold: 0.02 });
    });
  }
});

Notes: use Playwright's toMatchSnapshot or integrate pixelmatch/SSIM for more control. A threshold of 1-3% is a pragmatic starting point — tighten as you stabilize fonts.

Approach B — Programmatic shaping verification with HarfBuzz (WASM)

Pixel tests catch presentation errors, but you also need programmatic checks that the shaper outputs the expected glyph clusters and positions. Run HarfBuzz in CI (WASM) to verify shaping results against your baseline glyph sequences. This isolates shaping regressions caused by engine or font changes.

What to verify

Glyph sequence length and glyph IDs for a given font.
Cluster mapping to source codepoint indices (important for hit-testing/select).
Glyph advances/positions for label placement (kerning/shaping).

HarfBuzz WASM example

// tests/shape.spec.js
const hb = require('harfbuzzjs'); // harfbuzz wasm binding
const fs = require('fs');

(async () => {
  await hb.ready;
  const fontBuffer = fs.readFileSync('./fonts/NotoSansArabic-Regular.ttf');
  const face = hb.Face.create(fontBuffer);
  const font = hb.Font.create(face);

  const text = 'شارع';
  const buf = hb.Buffer.create();
  buf.addText(text);
  buf.guessSegmentProperties();

  hb.shape(font, buf, []);
  const glyphInfos = buf.json(); // library returns cluster/gid/pos data

  console.log(glyphInfos);
})();

Store the JSON glyph mapping baseline for each fixture. When glyph IDs change due to font upgrades, the test will fail and force a deliberate baseline update after verification.

Detecting font fallback deterministically

Browsers will pick a fallback font when a glyph isn't in the primary face. You need to be able to detect which font was used in a rendering test. There are two pragmatic techniques:

FontFaceSet.check — use the CSS Font Loading API to test if a font supports a character (e.g., document.fonts.check("16px 'MapPrimary'", "字")).
Metric-differencing — render the text with the primary font and with candidate fallback fonts to compare widths/heights; matching metrics indicate the font used.

Font availability check (browser)

// in-page helper
function supports(fontName, text) {
  return document.fonts.check(`16px "${fontName}"`, text);
}

// usage:
// supports('MapPrimary','श') => false if not supported

Combine this with shaping checks: if the primary font doesn't support the script, ensure a known fallback (Noto family) is available and verify glyph continuity.

Accessibility and grapheme cluster checks

Labels are not only visual — they’re interactive and need correct a11y. Two common failures: wrong screen-reader names due to invisible control characters, and broken selection/caret behavior caused by incorrect grapheme segmentation.

Tests to include

Verify accessible name equals the intended label (aria-label or innerText).
Use Intl.Segmenter to assert expected grapheme cluster counts for selection and cursor placement.
Ensure U+200E/U+200F directional marks are present only when intentional.

// accessibility.spec.js
const { test, expect } = require('@playwright/test');

test('accessible name and grapheme clusters', async ({ page }) => {
  await page.setContent(`شارع النور`);
  const name = await page.$eval('#label', el => el.getAttribute('aria-label'));
  expect(name).toBe('شارع النور');

  const clusters = await page.$eval('#label', el => {
    const seg = new Intl.Segmenter('ar', { granularity: 'grapheme' });
    return Array.from(seg.segment(el.textContent)).map(s => s.segment);
  });
  // assert expected cluster count or boundary positions
  expect(clusters.length).toBeGreaterThan(1);
});

Server-side/Tile rendering checks

If you render raster tiles server-side (Mapnik, MapServer, Skia/Canvas), run the same shaping verification against the server stack. Use HarfBuzz + FreeType on the tile build machine to confirm the glyph mapping before committing fonts to the tile renderer.

Practical tip

Use the same font files in both client and server test environments. Store font checksums in the repo so CI can detect unexpected font updates that could change glyph metrics.

CI integration and baseline management

Make visual diffs part of pull requests but avoid brittle failures. Use a staged policy:

Run fast shape-only tests (HarfBuzz) — fail the build if shaping differs.
Run visual snapshot tests with a relaxed threshold — fail the build only on large diffs.
On PR, upload diff artifacts and a difference heatmap for reviewers.
Allow maintainers to accept a new baseline after manual checking and bump font checksums.

Handling flaky or platform-dependent differences

Some differences are unavoidable (OS-level font rendering, subpixel antialiasing). Strategies to reduce flakiness:

Pin headless browser versions in CI (use Playwright's driver bundle).
Use webfonts to avoid system font variance for primary labels.
Set deviceScaleFactor and disable font-synthesis where possible.
Compare glyph metrics (advances/positions) in addition to pixels — these are more stable.

Troubleshooting checklist

Tofu boxes? - Check font coverage via document.fonts.check and HarfBuzz coverage tables.
Broken shaping? - Verify language tag & script properties passed to the shaper; use buffer.guessSegmentProperties() or set lang/script explicitly.
Bidi ordering wrong? - Ensure correct UBA (Unicode Bidirectional Algorithm) implementation; browsers do this, but server shapers may need explicit bidi processing.
Selection misaligned? - Confirm cluster-to-glyph mapping and use grapheme boundaries for cursor movement.
CI passes locally but fails on remote? - Compare font checksums, browser versions, and deviceScaleFactor.

Advanced strategies for large mapping teams

Font subset and hashing: Generate deterministic subfonts per region and store their hashes to detect inadvertent updates.
Auto-accept baselines by script: When only emoji or punctuation changes and impact is limited, a script can auto-update baselines with a manual audit step later.
Golden glyph tables: Maintain a canonical glyph sequence table for critical POIs and run nightly checks to detect upstream changes in font tooling.
WebAssembly shaper sandbox: Run the same HarfBuzz WASM binary both in CI and in server staging to ensure parity.

Pro tip: Use both shaping verification (HarfBuzz) and visual snapshots. One catches the logical mismatch, the other catches final presentation regressions.

Example test checklist for a PR

Does the PR add or modify fonts? If yes, update font checksums and run full visual tests.
Have any label strings been modified? Run shape tests and update glyph baselines.
Run accessibility checks for new interactive labels (aria-label, text selection).
Review image diffs and glyph diffs and sign off on non-breaking updates.

Putting it together: A minimal repo layout


repo/
  tests/
    label-render.spec.js   // Playwright visual tests
    shape.spec.js          // HarfBuzz shaping tests
    accessibility.spec.js  // a11y and grapheme tests
  fixtures/
    labels.json
  baselines/
    lat-accent.png
    arab-shape.json       // glyph mapping baseline
  fonts/
    NotoSansArabic-Regular.ttf
    MapPrimary.woff2
  scripts/
    update-baselines.js

Actionable takeaways

Run HarfBuzz shaping as unit tests — it catches logic regressions earlier and cheaper than image diffs.
Use Playwright visual tests for final verification, with SSIM-based diffs and conservative thresholds.
Detect fallback deterministically using document.fonts.check and metric differencing.
Test accessibility and grapheme boundaries — they are often overlooked and cause UX bugs.
Pin fonts and browser versions in CI and store checksums for traceability.

Future predictions (2026+)

Expect continued adoption of deterministic, WASM-based shaping for parity across client and server, and richer font-fallback APIs in browsers that expose coverage checks. Variable fonts will bring complexity to metric stability, so teams will move toward glyph-level baselines (rather than pixel-only). Combining shaping verification with perceptual diffs will become the recommended practice for production-grade cartography rendering.

Final checklist before shipping a map update

All labels pass HarfBuzz shaping tests.
Visual diffs within tolerance for each critical language region.
Font checksums and baselines updated if fonts changed.
Accessibility tests green for interactive labels.
CI artifacts include heatmaps and glyph mapping JSON for rapid review.

Call to action

Ready to adopt this test suite? Clone the example repo (link in the repo description), run the Playwright and HarfBuzz tests in your CI, and iterate on thresholds per-region. If you want a tailored checklist for your tile stack (Mapnik, Skia, or custom renderer), download the sample fixtures and run them against your build — then open a PR with results and we’ll help triage failures.

Start now: add a HarfBuzz shaping test and a single Playwright snapshot for one critical language. You’ll catch your next shipping incident before customers do.

Unknown

Contributor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.