Files
faunosteo/docs/development/TEST_STRATEGY.md
T
bchanot b0cce2cd8c docs(docs): add SaaS implementation plan and architecture docs (step 0)
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.
2026-10-08 21:41:39 +02:00

87 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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).