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`](../../../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](https://github.com/gridaco/grida/blob/main/fixtures/README.md)). ### 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.