From c57abbe89562cd8fe29a532bd0eddbdd5a228518 Mon Sep 17 00:00:00 2001 From: Amin Mousavi Date: Fri, 11 Sep 2026 19:57:45 +0800 Subject: [PATCH] docs: say component tests are allowed, not absent by rule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md read as a prohibition — "Vitest for its own pure helpers only, no React, no DOM". It was only ever a description of what was installed, and it was talking future contributors out of a test they are allowed to write. Tests now states what exists, that component tests are allowed, and what the first one costs: jsdom or happy-dom, @testing-library/react v16+ for React 19, environment and a *.spec.tsx include. Notes that babel-plugin-react-compiler is in devDependencies but not enabled in next.config.ts, so there is no transform mismatch to work around. Adds which to reach for. A decision belongs in a pure test, extracted into components/{feature}/. A defect only a real render shows — ref-versus-state timing, effect ordering — belongs in a component test, because no pure test can see it. VoiceReviewSheet is the cheap first one; TreatmentWorkspace needs six axios mocks and earns its keep only for a bug that needs it. Same correction in vitest.config.ts's docblock and the spec's §12 line, which each carried their own copy of "no React, no DOM". Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 12 ++++++++++-- docs/specs/voice-treatment-entry/spec.md | 10 ++++++---- frontend/vitest.config.ts | 7 +++++-- 3 files changed, 21 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3002bb5..9d118ed 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,7 +39,7 @@ There is **no root `package.json`**. Every npm command runs inside `backend/` or | `npx tsc --noEmit` | **Verification gate for any type or cross-cutting frontend change** | | `npm run build` | Production build (`output: 'standalone'`) | | `npm run lint` | ESLint via Next | -| `npx vitest run` | Vitest — pure helpers only (`prosthesisTree.ts`, `voiceReviewRows.ts`, `toothSelectionGroups.ts`, `voiceApply.ts`) | +| `npx vitest run` | Vitest — today the pure helpers in `components/treatment/*.spec.ts`; component tests are allowed, see **Tests** | `NEXT_PUBLIC_*` values are baked in at build time — restart `npm run dev` after changing `.env.local`. @@ -104,7 +104,15 @@ Clinics may only dispatch to labs they are linked to: `OrganizationLink` (A↔B, ### Tests -Jest covers pure logic only — permission normalization, phone/timezone helpers, task generation, lab-send validation, voice extraction contract (`backend/src/**`). Frontend has Vitest for its own pure helpers only — no React, no DOM: `prosthesisTree.ts`, `voiceReviewRows.ts`, `toothSelectionGroups.ts` and `voiceApply.ts` (`frontend/src/components/treatment/*.spec.ts`), run via `npx vitest run`. When a component callback holds a decision worth testing, extract the decision into `components/{feature}/` and leave the commit — state, refs, save order — in the component; `voiceApply.ts` is the worked example. `npx tsc --noEmit` remains the frontend's cross-cutting gate. +Jest covers pure logic only — permission normalization, phone/timezone helpers, task generation, lab-send validation, voice extraction contract (`backend/src/**`). + +Frontend runs Vitest (`npx vitest run`). `npx tsc --noEmit` remains the cross-cutting gate. + +**What exists today** is pure-helper specs under `frontend/src/components/treatment/*.spec.ts` — `prosthesisTree.ts`, `voiceReviewRows.ts`, `toothSelectionGroups.ts`, `voiceApply.ts`. `vitest.config.ts` therefore sets no `environment` and includes `*.spec.ts` only. + +**Component tests are allowed.** Nothing here forbids them; the setup simply is not installed yet. Adding the first one means `jsdom` (or `happy-dom`) and `@testing-library/react`, plus `environment: 'jsdom'` and a `*.spec.tsx` include in `vitest.config.ts`. React 19 needs testing-library v16+. The React compiler babel plugin is in `devDependencies` but **not** enabled in `next.config.ts`, so there is no transform mismatch to work around. + +**Which to reach for.** Prefer a pure test when the thing under test is a decision: extract it into `components/{feature}/` and leave the commit — state, refs, save order — in the component. `voiceApply.ts` is the worked example, pulled out of a callback in `TreatmentWorkspace.tsx`. Reach for a component test when the defect is only visible in a real render — ref-versus-state timing, effect ordering, a callback firing before a re-render — because no pure test can see those. Start with a small, prop-driven component (`VoiceReviewSheet` is the easy first one); rendering `TreatmentWorkspace` means mocking next-intl, the i18n router and six axios modules, so it earns its keep only for a bug that needs it. ## Deployment diff --git a/docs/specs/voice-treatment-entry/spec.md b/docs/specs/voice-treatment-entry/spec.md index f2dd37f..d61975d 100644 --- a/docs/specs/voice-treatment-entry/spec.md +++ b/docs/specs/voice-treatment-entry/spec.md @@ -1062,10 +1062,12 @@ enabling this for real clinics. - `cd backend && npm run prisma:migrate && npm run prisma:seed` — the new `CatalogEntityKind` values and their translation rows. The seed never wipes, so re-running it is safe. - `cd frontend && npx vitest run` — **new**. One dev dependency, one config, one script, - covering the pure helpers only: `prosthesisTree.ts` (stack legality, `applyLeafToJobs` - precedence, `toothRegionColors`) and `voiceReviewRows.ts` (row availability, the merged - row, folding chips into the result). No React, no DOM. `CLAUDE.md` is updated in the same - commit — "there are no frontend tests" stops being true. + covering `prosthesisTree.ts` (stack legality, `applyLeafToJobs` precedence, + `toothRegionColors`), `voiceReviewRows.ts` (row availability, the merged row, folding chips + into the result), `toothSelectionGroups.ts` and `voiceApply.ts` (the apply decision). + Pure functions, so no DOM environment is configured — a limit of what exists, not a rule + against component tests; `CLAUDE.md` > Tests says what adding one costs. `CLAUDE.md` is + updated in the same commit — "there are no frontend tests" stops being true. - `cd frontend && npx tsc --noEmit` — frontend type gate. - `cd frontend && npm run build` — production build. - ESLint on every touched file, no new warnings. diff --git a/frontend/vitest.config.ts b/frontend/vitest.config.ts index 7af964d..0bf7771 100644 --- a/frontend/vitest.config.ts +++ b/frontend/vitest.config.ts @@ -2,8 +2,11 @@ import path from 'node:path'; import { defineConfig } from 'vitest/config'; /** - * Covers the pure helpers only — no React, no DOM. `@/*` mirrors `tsconfig.json`'s path so a - * spec can import the same modules the app does. + * Covers the pure helpers, which is all that exists today — hence no `environment` and a + * `*.spec.ts` include. Component tests are not ruled out: add jsdom, @testing-library/react, + * `environment: 'jsdom'` and `*.spec.tsx` here. See CLAUDE.md > Tests. + * + * `@/*` mirrors `tsconfig.json`'s path so a spec can import the same modules the app does. */ export default defineConfig({ resolve: {