fixtures

name	fixtures
description	Guides authoring, organizing, and referencing test fixtures across the engine repo. Use when creating new fixtures, writing tests that depend on fixtures, or deciding what should be checked into git.

Fixtures

What fixtures are

Fixtures are static input files — HTML, SVG, CSS, JSON, .grida, font binaries, images, text samples — used as deterministic inputs to rendering, parsing, and I/O tests. They exist so that tests are reproducible, self-contained, and don't depend on external services or generated data.

Why we keep them

• Regression detection — render the same input, compare the output.
• Spec coverage — each fixture maps to a specific feature or property being tested (one concept per file).
• Onboarding — new contributors can see exactly what the renderer handles by browsing fixtures.
• Cross-pipeline validation — the same fixture can be consumed by unit tests, golden tests, reftests, probe tests, and visual inspection.

What should be covered

A fixture should exist for every rendering behavior, format variant, or edge case that the engine supports or intends to support. This includes:

• Each CSS property / SVG element the htmlcss or SVG renderer handles
• Format I/O round-trips (SVG → Grida, .grida decode)
• Edge cases: zero-size, empty content, deeply nested, degenerate inputs
• Unsupported-but-tracked features (the fixture documents the gap)

Best practices

• One concept per file. Don't combine unrelated properties.
• Self-contained. No external resources, network fetches, or scripts.
• Minimal. Only enough structure to isolate the behavior under test.
• Probe-friendly. High-contrast palette (prefer B/W), round pixel values, ≤ 3 colors. Designed for headless pixel probing, not human aesthetics.
• Descriptive naming. <domain>-<property>[-<descriptor>].<ext> — the filename alone should tell you what's being tested.
• Labeled specimens. Within a fixture, label each test case with the value being exercised so both humans and heuristics can identify regions. Keep labels short, and pin the dimensions of any container holding a label (flex item, grid cell, stretched block) so font-advance-width differences between engines can't leak into box geometry. When a test pipeline offers a text-neutralizing stylesheet (e.g. fixtures/test-html/_reftest/hide-text.css for the htmlcss reftests), prefer that over stripping the label — keeping the text helps the next reader understand the fixture.
• Match the fixture's subject to the viewport policy. For refbrowser fixtures under fixtures/test-html/, paint / visual-property fixtures should size their root to a preset viewport (via min-height) so grida's cull and Chromium's screenshot have identical dimensions. Layout fixtures (box-model, flex, grid, intrinsic sizing) must NOT force a body size — the output dimensions are what the test measures; a min-height hack contaminates the result. See fixtures/test-html/README.md for the preset list, the paint-vs-layout rule, and the per-fixture viewport workflow for layout tests.
• Don't duplicate. Before adding a fixture, check if an existing one already covers the behavior. Extend or split rather than duplicate.

Git inclusion policy

Checked in (fixtures/)

All directories under fixtures/ except fixtures/local/ are committed to the repository. These are small, purpose-built files that are part of the test suite.

fixtures/
├── apple-emoji-linux/ # Emoji PNGs (compile-time input of the golden emoji example)
├── css/               # CSS stylesheets
├── fonts/             # Bundled font binaries (deterministic text tests)
├── images/            # Test images
├── prompts/           # AI prompt fixtures (model-v2 experiments)
├── test-grida/        # .grida format fixtures
├── test-html/         # HTML+CSS renderer fixtures (L0, etc.)
├── test-svg/          # SVG fixtures
├── text/              # Plain text samples
├── text-editor/       # Shared text-editing command fixtures (v1.json)
└── local/             # ← gitignored, see below

The grida product repo holds frozen snapshots of fonts/, images/, test-grida/ and text-editor/ for its staying TS tests — canon and history live HERE. If a fixture in those four dirs evolves, the grida side follows only by a deliberate re-snapshot (grida fixtures README).

Not checked in (fixtures/local/)

fixtures/local/ is gitignored. It holds large, third-party, or benchmark-only datasets that are meaningful for local development but too large or license-restricted for the repository:

• W3C_SVG_11_TestSuite — W3C SVG 1.1 conformance suite (~50 MB)
• resvg-test-suite — resvg's feature-focused SVG tests
• oxygen-icons-5.116.0 — icon set for stress testing
• perf — large scenes for benchmarking
• refig — Figma community-file render corpus (workflow documented in the render-reftest skill; source tooling lives in the grida repo)
• svg-issues — reduced repro cases for SVG bugs

These must be downloaded separately by developers who need them.

Referencing local-only fixtures

Never reference fixtures/local/ paths in committed code, tests, or documentation. Local fixtures do not exist in CI or on other developers' machines. Specifically:

• Do not include!(), read_to_string(), or fs::read() a local/ path in any Rust test or example that runs in CI.
• Do not hardcode fixtures/local/ paths in docs, READMEs, or AGENTS files as if they are always available.
• If a doc needs to mention a local suite (e.g. for reftest instructions), clearly mark it as local-only and note that the developer must download it first.
• Tests that depend on local fixtures must be gated (e.g. #[ignore] with a comment, or behind a feature flag) so they don't fail in CI.