Eight documents under docs/development/ confronting the approved business architecture with the audited code: 27-step plan, repository migration map, domain map, frontend/backend architecture, migration and test strategy, open questions. Reference document placed at the repository root.
87 lines
8.2 KiB
Markdown
87 lines
8.2 KiB
Markdown
# Test strategy
|
||
|
||
Status: Step 0 deliverable, 2026-10-08. Current state: 32 files under
|
||
`tests/unit/`, 180 `it(` cases, vitest 3 + happy-dom, no browser, no e2e
|
||
(audit 13). All green per TODO as of 2026-07-12; not re-run in Step 0.
|
||
|
||
## 1. Layers
|
||
|
||
| Layer | Tool | Location | Runs in |
|
||
|---|---|---|---|
|
||
| Unit (pure TS, Zod, services) | vitest | `apps/app/tests/unit`, `packages/*/tests` | CI on every PR |
|
||
| Component | vitest + @testing-library/react + happy-dom | `apps/app/tests/components` | CI |
|
||
| Integration (app ↔ local Supabase) | vitest with `supabase start`, test users created via the admin API in a fixture | `apps/app/tests/integration` | CI job with the Supabase stack |
|
||
| Database (schema, functions, triggers) | pgTAP via `supabase test db` | `supabase/tests/db` | CI, before app tests |
|
||
| RLS | pgTAP, per table, per role | `supabase/tests/rls` | CI, release gate |
|
||
| End-to-end | Playwright against `pnpm preview` + local Supabase | `apps/app/e2e` | CI nightly + release gate |
|
||
| Migration | `supabase db reset` from zero + seed + regression fixtures | CI | every PR touching `supabase/` |
|
||
| PDF regression | vitest golden tests: text extraction of generated PDFs, attachment roundtrip, raster hash on fixed inputs | `packages/pdf/tests` | CI |
|
||
| SQL/TS contract | generated types diff check | CI | every PR touching `supabase/` |
|
||
|
||
Browser-only code (`svgToPng`, `DOMParser` in the importer) runs under
|
||
happy-dom where sufficient and under Playwright when real rendering matters
|
||
(raster hash).
|
||
|
||
## 2. Tests required BEFORE migration (plan Step 1)
|
||
|
||
These pin the behaviour that later steps must preserve. They are written
|
||
against the *current* code, on real data, without changing the application.
|
||
|
||
| Area | Test to add | Why before |
|
||
|---|---|---|
|
||
| Click chain | `EditorRoute.onZoneClick` branches: detail trigger opens modal and is never added; no active observation → fallback then click lost; spine zone adds + opens picker and never removes; bilateral → picker, both sides present → removes both; plain toggle. Extract nothing yet: test through the route with mocked `loadSvg`. | The chain moves to a service in Step 5; zero tests today (audit 13 §4). |
|
||
| Spine sync on real SVG | `collectSpineVertebrae` / `syncSpineZones` with bones parsed from the real `Horse.svg` (not fixtures). | `regionFromLabel` is replaced by region codes; must prove equivalence. |
|
||
| SVG ↔ catalog | Parse both real SVGs, run `matchZoneFindings` on all 27 annotations against the 26 catalog zones: 26 score-0 matches, trigger unmatched, zero orphan catalog zones. Table from audit 06 §4 becomes the expected output. | The importer must reproduce exactly this mapping. |
|
||
| `opens-detail` ↔ manifest | every `data-anno-opens-detail` value is a key of `species.details`, and every key has a trigger. | Becomes `parent_view_id`/`opened_by_annotation_id` invariants. |
|
||
| Matcher parity | the inline matcher of `pathology-editor.html` (extracted by regex from the file at test time) gives the same result as `zoneMatch.ts` on all 26 + edge labels. | LRN-026 recommendation; protects the editor until deletion. |
|
||
| Catalog copies parity | `src/.../pathologies.json` byte-equal to `public/species/equine/pathologies.json`. | Guards the dual-copy quirk until removal. |
|
||
| Catalog invariants | `zone.id === key`, 26 zones, category ids per zone, `requires_vet_referral` only on leaves, the `ssb-dysfunctions` under `sphenoid` anomaly asserted as *known* (so a fix is a deliberate change). | Importer normalisations are tested against these facts. |
|
||
| Full PDF roundtrip | Export a report with: a plain zone, a bilateral zone both sides, a spine zone with vertebrae, a detail zone, findings with vet flag, free text, severity, comment, conclusion, next appointment; `rasterizeSvg` real under happy-dom or stubbed deterministically; re-import; deep-equal. Then extract page text and assert the `ZONES`, `CONSTATS — <ZONE>`, `(Gauche)`, `(C3, C4)`, `(!)` strings. | Current roundtrip uses `observations: []` (audit 13 §4). The PDF step rewrites the pipeline. |
|
||
| Attachment fallback | `traverseForJsonAttachment` on a PDF whose attachment was re-saved by another tool. | Untested path handling user data. |
|
||
| Golden fixtures | `tests/fixtures/report-v2.full.json` (the report above) + `report-v2.minimal.json`, frozen. | Inputs for the `v2ToV3` adapter tests. |
|
||
| Orphan findings | removing a zone / pruning a region leaves findings; assert current behaviour. | Migration decides to keep or clean (I4). |
|
||
| Species registry | `getAllSpecies()` returns only equine; `AnimalForm` default `'equine'`. | Replaced by DB species; test is deleted with the registry. |
|
||
|
||
Target after Step 1: roughly 230–250 cases, all current ones untouched.
|
||
|
||
## 3. Tests per future domain (what each step must ship)
|
||
|
||
| Domain | Unit | DB / RLS | Integration / e2e |
|
||
|---|---|---|---|
|
||
| Identity | profile form validation, role helpers in TS mirrors | `is_platform_*`, profile trigger, roles RPC denies self-grant | sign-up, verify email, login, logout |
|
||
| Verification | status machine | expiry trigger, reviewer-only transitions | upload document → pending → admin verifies |
|
||
| Organizations | none | membership RPC, secretary cannot become practitioner, seat exclusivity | create cabinet, invite, switch context |
|
||
| Clients / Animals | normalisation of contacts, consent payloads | `can_view_client/animal`, grants expiry/revocation, candidate match reveals nothing cross-tenant | create client+animal, share with another practitioner via consent flow |
|
||
| Anatomical Sheets | document Zod, importer special cases (audit 07 list), renderer attribute emission, GC preconditions in TS mirror | immutability trigger, numbering, `can_use_sheet`/`can_fork_sheet`, GC function with each precondition | seed equine v1, open it in the editor read-only |
|
||
| Reports | document v3, `v2ToV3`, zone interaction service, autosave throttling, outbox | numbering concurrency, completion + quota (5th ok, 6th denied, deleted counts, import counts), `free_edit_until`, revisions on checkpoints, restore | create → autosave → complete → PDF → reopen; offline edit → reconnect → conflict revision |
|
||
| PDF | golden text, attachment v3, snapshot sufficiency (render with the sheet row deleted) | none | export, download, import into another account denied |
|
||
| Editor merge | one test per legacy operation (audit 03 §2, 05 §3.5), create detail view geometry | publish creates v2, v1 reports still render | annotate, publish, use in a report |
|
||
| Community | none | follow grants use, unfollow revokes, private needs grant, fork provenance, moderation roles | discover, follow, fork |
|
||
| Booking / Travel / Calendar | expiry rule function (48/24/1h) as pure TS mirror and SQL, availability engine with provider mock | slot lock under concurrent requests, one pending per client | public booking → practitioner confirms → reminder queued |
|
||
| Billing | entitlement derivation, referral rules | `get_effective_entitlements`, Stripe webhook idempotency | checkout in Stripe test mode |
|
||
| Imports | adapters on sample files, duplicate detection | atomic commit, quota preflight | CSV import preview → confirm |
|
||
| Admin / Audit | none | append-only, impersonation expiry | admin MFA required |
|
||
| Hardening | header checks, dependency audit | full RLS matrix, storage policy matrix | cross-tenant scenarios (architecture Prompt 10) |
|
||
|
||
## 4. Fixtures and data
|
||
|
||
- Real equine SVGs and catalog are the primary fixtures for anatomy tests;
|
||
they are never edited (CLAUDE.md). Synthetic small SVGs cover error paths.
|
||
- `supabase/seed/test/` provides two practitioners, one cabinet, two clients,
|
||
three animals, the official sheet, one personal sheet, reports in each
|
||
status. RLS tests reuse it.
|
||
- Golden PDFs are compared by extracted text and attachment JSON, not by
|
||
bytes (pdf-lib dates and ids vary); raster hash only on fixed-size inputs.
|
||
|
||
## 5. CI gates
|
||
|
||
Per PR: `pnpm typecheck`, `pnpm lint` (0 warnings), `pnpm test:run`,
|
||
`pnpm build`; when `supabase/` changes: `supabase db reset`, `supabase test
|
||
db`, types diff. Nightly: Playwright suite. Release: full RLS matrix,
|
||
backup/restore rehearsal checklist, `pnpm audit`, secret scan.
|
||
|
||
## 6. Numbers to track
|
||
|
||
Test count per step and a "legacy tests deleted" count, so that deletions are
|
||
deliberate (each deleted test names the replacing test in its commit).
|