# Testing
- **Status:** Active proof strategy
- **Kind:** Normative testing owner
- **Authority:** Canonical for evidence, determinism, and proof layering
- **Owns:** What tests must prove and where proof belongs
- **Does not own:** Command syntax, implementation seams, or review result formatting
## Proof layers
Run the narrowest proof first:
1. Native interface tests prove deterministic scene generation, budget enforcement, stable tree and
topology IDs, measured-geometry validation, interaction ordering, route exclusion, and bounded
timing through `grafik::generate_scene` and `grafik::simulate_scene`.
2. Existing native outcome-tracer tests remain until that implementation is absorbed.
3. WASM build proof verifies the shallow adapter compiles and generates browser bindings.
4. Dependency-free Node tests prove the standalone lab uses only local Grafik assets and the concrete
adapter maps every scene primitive, measured anchor, interaction, and reduced-motion trace without
ambient randomness.
5. Manual browser proof checks the candidate grid, clickable interactions, real geometry, connector
placement, resize behavior, no-JavaScript reading, reduced motion, 320 CSS-pixel reflow, and console
errors.
6. `cargo make check` is the complete local default gate.
Tests exercise public interfaces. Moving a test outward must not widen the production interface.
## Determinism
Default tests must not depend on wall clock, ambient randomness, network access, locale, filesystem
order, or live services. Use explicit geometry, nonzero seeds, integer simulation time, sorted output,
and exact trace comparison. A replay failure must print the seed and input through the assertion.
Required native behaviors:
- all four final dispositions and their simulated or recorded source remain distinct in the public
trace and JSON;
- identical input and seed produce identical complete traces and JSON;
- invalid or overlapping geometry fails before producing events;
- grown segments remain outside panel interiors except at selected ports;
- `SUCCEEDED` emits weighted progress, one bounded pulse, and leaf-first retraction;
- `FAILED` emits one bounded decorative glitch and no successful progress;
- `UNKNOWN` emits a two-second seeded burst at 1–3 marks per second, with normal and rare density
limits independently asserted;
- `NOT_ATTEMPTED` emits no receiver cue;
- every profile's density, lifetime, displacement, and duration remain within `PATTERNS.md` budgets.
## Snapshot vocabulary and policy
Use distinct names for distinct state:
- A **conformance snapshot** is a reviewed, committed, exact serialized input/output example for one
public Rust or WASM interface.
- A **variation** is a user-authored set of effect parameter values. It is product data, not test
evidence.
- A **checkpoint** is a time-aware observation in a displayed flow. It is domain data, not a saved
editor state or test artifact.
- A **visual baseline** is a screenshot produced in a pinned browser environment. It proves concrete
rendering only and cannot replace semantic or invariant tests.
Conformance snapshots complement, never replace, direct assertions. Use direct tests for validation,
budgets, graph invariants, error behavior, and properties across seed corpora. Use snapshots for
complete stable examples whose accidental field, ordering, identifier, or timing drift must be
reviewed as a contract change.
A conformance snapshot contains an explicit case name, schema version, byte-equivalent input, and
byte-equivalent output. Inputs include every seed, time, geometry rectangle, interaction, and budget;
they contain no ambient values. Snapshot serializers use stable struct order and sorted collections;
production snapshot surfaces must not expose unordered maps.
Snapshot updates are a review operation, not a test side effect. The check path never rewrites a
committed baseline. An update path writes received candidates outside the committed baseline tree,
then requires an explicit per-file accept or reject step. Do not bulk-accept unexplained changes.
Every accepted change states which contract changed and why. CI runs snapshot checks but never the
accept path.
Pin a small representative corpus rather than every seed: one minimal case, each closed component or
effect kind, each semantic result, one maximum-budget case, one reduced-motion trace, and named rare
seeds. Property tests continue to scan wider seed ranges for invariant and budget failures.
Required receipt-scene behaviors:
- byte-equivalent request and seed produce identical complete scene plans and JSON;
- separate random streams keep layout stable when only effect timing implementation changes;
- invalid content or impossible budgets fail before seeded choices advance;
- all scene trees remain within node/depth limits and use unique stable IDs;
- lists, tables, actions, menus, and every diagram form survive serialization;
- every diagram edge references existing topology nodes;
- every effect references an existing target and every action references a bounded script;
- button sizes, layouts, diagrams, pattern profiles, and phases vary across a pinned seed corpus;
- byte-equivalent plan, geometry, and interaction produce identical complete traces and JSON;
- missing, duplicate, stale, or non-finite measured geometry is rejected;
- every live-effect, density, lifetime, displacement, fragment, phase, and total-duration budget holds;
- no event can target or move readable text; and
- the complete default gate reads or writes no sibling checkout.
## Browser evidence
Automated adapter tests do not prove browser layout, accessibility tree behavior, or visual quality.
Before a visual change is accepted, manually check keyboard reading order, reduced motion, no
JavaScript, 320-pixel width, text-spacing overrides, light/dark preference, and browser console.
## Meaningful-change record
```text
Contract:
Surface:
Gate:
Risk:
```
A passing gate does not erase unproved browser or visual risk; state it.