Fixtures

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.