10 KiB
Characterisation report (plan Step 1)
Status: done 2026-10-08, branch feature/step-01-characterisation-tests.
Note 2026-10-10 (Step 5): the legacy suites this report lists were replaced one-to-one
by suites on the canonical sheet (services.zoneInteraction, sheets.provider,
state.reportStore, pdf.roundtrip, components.*, routes.EditorRoute); the
frozen v2 fixtures (report-v2.*.json, report-v2.*.pdf) remain the oracle of the
v2 → v3 migration.
Scope: a tested photograph of the current application before any SaaS
transformation. No file under src/, public/, scripts/, docker/ was
changed. Commands run on this host: Node 24.21.0, pnpm 10.13.1 (corepack),
dependencies installed from the lockfile.
1. Results
| Command | Result |
|---|---|
pnpm test:run |
39 files, 271 tests green (180 pre-existing + 91 new) |
pnpm typecheck |
0 errors |
pnpm lint |
0 errors, 0 warnings |
pnpm build |
OK (chunk-size warning pre-existing) |
2. Files added
| File | Cases | Characterises |
|---|---|---|
tests/fixtures/report-v2.full.json |
fixture | Golden Report v2 with every zone kind (plain hinge, bilateral both sides, spine with vertebrae, detail-popup), catalog findings with vet flag and side, free text, severity, comment, conclusion, recommendations, dated next appointment. Real data-anno-id and catalog paths. |
tests/fixtures/report-v2.minimal.json |
fixture | Smallest valid v2 report. |
tests/fixtures/README.md |
doc | Fixture contract: never edited to make a test pass. |
tests/unit/char.catalog.test.ts |
13 | pathologies.json: byte parity of the two copies, Zod acceptance, schema_version, species, the 26 zone keys in order, zone.id === key, 3 categories per zone, root-category id convention with the known sphenoid → ssb-dysfunctions anomaly, 792 nodes / 612 leaves / depth 3 / 228+384, 41 vet flags all on leaves, 62 description_fr, 0 description_en, 0 sources, sibling-only id uniqueness (26× anamnesis, 11× amplitude-asymmetry), three anamnesis content variants (8/9/9 zones). |
tests/unit/char.svgCatalogLink.test.ts |
18 | Raw attribute census of both SVGs (48/48/18/47/47/18/5/1), five category slugs, 27 distinct ids, Horse_head.svg = same drawing + different viewBox, the full 26-row mapping table annotation → catalog zone with score 0 in EN and FR, trigger unmatched, no orphan zone, substring rule unreachable, the two FR pairs inside the fuzzy tolerance (distances 5 and 3), opens-detail ↔ manifest coherence, spine helpers on the real file (region → polygon id, spawn, collect order, detail-sourced exclusion). |
tests/unit/char.pathologyEditor.test.ts |
8 | The inline matcher of public/pathology-editor.html evaluated from the file and compared to zoneMatch.ts on all 27 annotations + edge labels (LRN-026 parity test), generateId slug rules, 76/76 inline translation keys disjoint from the app dictionary, shared osteo:locale key, hard-coded SPECIES_CONFIG pointing at existing files, zero src/ imports, noindex, no Zod. |
tests/unit/char.clickChain.test.tsx |
12 | EditorRoute through the DOM on the real SVGs: disclaimer once per session (osteo:disclaimer-shown), plain toggle add/remove and data-state="current", collapsed-card fallback (click re-activates the last observation and is lost), detail trigger opens the modal and is never a zone, zones clicked in the modal carry detailSourceId: 'head', spine click adds + opens the picker on the right tab and never toggles off, cancel leaves a zone without vertebrae, picker spawns another region and prunes to zero, bilateral left / right / both and "both present → clear both", ✕ removal keeps orphan findings (known, BDR-019), one picker per (catalog zone, side) and raw-id badge for the unnamed trigger. |
tests/unit/char.pdfFull.test.ts |
15 | Export of the full fixture: page count, title/author metadata, re-fetch of SVGs and logos at export time, ZONES as bullet rows with (C3, C4) / (Gauche) suffixes, one CONSTATS — <ZONE> section per (zone, side) with snapshot labels and the (!) marker, free findings / severity / comment / view captions, conclusion page and header identity on every page, EN variant with identical attachment, deep-equal roundtrip, attachment dictionaries (/F (osteo-report.json), /AFRelationship /Data, /Desc UTF-16 "Faunosteo state v2", /Subtype /application#2Fjson, Flate), pdf-lib 1.17.1 has no getAttachments so the traversal is the production path, incompatible_version with foundVersion 3, foreign attachment and Zod-invalid attachment both reported as no_attachment (known), orphan finding printed under its zone, unknown ids printed raw. |
tests/unit/char.schemaPersistence.test.ts |
13 | Zod: fixtures accepted unchanged, unknown keys stripped, version literal 2, unbounded vertebra index (C99), French severity enum, orphan findings accepted, unknown species accepted, duplicate boneId with sides / detail. Persistence: full fixture mirrored to and restored from osteo:draft, hydrateReport does not revalidate, initReport shape, osteo:lastPractitioner, osteo:locale. |
tests/unit/char.i18nSpecies.test.tsx |
12 | Dynamic keys (severity.*, vertebra.region.*, home.import.error_* with {version}, pdf.section.*/pdf.view.*), 71 svg_editor.* keys, label fallbacks, registry = equine only with the committed formula, catalog loader species id, NewReportRoute select defaults to equine with one option, scaffold script quirks (schema_version '1.1', T13 default). |
Pre-existing tests reused as-is: all 32 files (180 cases). They already
cover: SVG parser rules and counts (anatomy.*), zoneMatch on a synthetic
catalog, spineZones on synthetic bones, VertebraPicker, FindingsTreePicker,
schemas, store actions and draft mirror, practitioner cache, locale,
dictionary parity, minimal PDF roundtrip, attachment extraction and the 16 MiB
inflate cap, buildZoneLabels, rasterizeSvg, UI primitives.
3. Behaviours characterised (summary)
- Report: schema acceptance boundary, store init/hydrate, persistence keys, draft restore.
- Anatomy: real SVG attributes and categories, id spaces, parser output, spine region inference and sync on real data.
- Findings: catalog structure, counts, conventions, anomalies, SVG ↔ catalog link table, matcher behaviour and fragile pairs.
- Pathology editor: matcher parity, id generation, translations, config, isolation.
- Click chain: every branch of
onZoneClickand the three pickers' effect on the store. - PDF: full export text, pages, attachment format, import error kinds, degradation on missing assets.
- i18n: dynamic keys, fallbacks, dictionary surface tied to legacy tools.
- Special cases: detail trigger, orphan findings, disclaimer flag, unbounded vertebra index, unknown species, foreign attachments.
4. Behaviours NOT characterised, and why
| Area | Reason | Where it will be covered |
|---|---|---|
SVG editor (SvgEditorRoute.tsx, 1858 lines) |
Vanilla DOM inside a useEffect, state in the DOM, drag/mouse geometry depends on getScreenCTM which happy-dom does not implement. Testing it would require rewriting it (forbidden in this step). |
Replaced by the merged editor (plan Step 17); its operations are listed in audit 03 §2 and become reference tests of the new model. |
| Pathology editor DOM behaviour (tree add/edit/delete, dirty flag, download) | 1700 lines of imperative DOM in an IIFE with no export; only the pure functions were extracted by text. | Merged editor findings panel (Step 17). |
Real rasterisation (rasterizeSvg on the real SVG) |
No canvas in happy-dom; a 1×1 PNG stub is used. The existing pdf.svgToPng test covers the function with mocks. |
Playwright raster hash at the PDF step (Step 6) or later e2e. |
| Visual PDF layout (positions, wrapping, pagination) | Only drawn strings are captured, not coordinates. | PDF golden comparison by extracted text stays; layout is a visual QA item. |
| Vertex-level SVG geometry | cx/cy/points are never read by the app; no behaviour to pin. |
Importer tests (Step 4) when geometry becomes data. |
window.alert on export failure, download anchor click |
Side effects of the route; no value in pinning. | e2e. |
| Browser e2e (real routing, file input import, download) | No Playwright in the repo; adding it is tooling work outside this step. | See §6. |
5. Problems discovered (none fixed, by rule)
- Host tooling: this machine had no
pnpmand nonode_modules; CLAUDE.md says pnpm is at~/.local/bin/pnpm, which does not exist. Node is 24.21.0, not 20. Usedcorepack prepare pnpm@10.13.1(the Dockerfile pin). CLAUDE.md note is stale. - Import error cause lost: a Zod-invalid attachment and a foreign JSON attachment both surface as
no_attachment(audit 08 B.2, pinned as known). - ZONES rendering: the ' · ' joined value is split back into bullet rows by the renderer; harmless, but the dictionary-level
pdf.emptyfallback is printed when an observation has findings but no zone. - Fuzzy tolerance: the FR pairs fetlock ant./post. and sacral/caudal are inside the Levenshtein threshold (5 ≤ 7, 3 ≤ 4); unreachable today only because EN labels are exact.
- Scaffold script writes
schema_version '1.1'and a mixed formula (known, script slated for removal). - README still says 174 tests (actual before this step: 180). Not edited in this step to keep the diff to tests and docs; corrected at Step 2 with the workspace move.
6. To cover in a future e2e suite
- Full flow:
/→/new→/editor→ zones of each kind → findings → export → download → re-import from/. - Session persistence across a real reload (sessionStorage) and language switch mid-edit.
- Detail modal interactions with real pointer events (tooltip hidden on the trigger).
- PDF opened in a viewer: attachment visible, pages readable, raster images present.
- Mobile viewport layout of the editor.
7. Known obsolescence
Tests in char.clickChain.test.tsx and char.pdfFull.test.ts are written
against the current route and export signatures. Plan Step 5 (zone service,
document v3) and Step 6 (PDF v3) will replace them one-to-one; each deleted
test must name its replacement in the commit message (TEST_STRATEGY.md §6).
char.pathologyEditor.test.ts and the svg_editor.* key count die with the
legacy editors (Step 17). char.catalog.test.ts and
char.svgCatalogLink.test.ts become the oracle of the legacy importer
(Step 4) and survive as long as the seed files exist.