docs: generate project documentation

2026-06-10 18:17:51 -04:00
parent 581b31916b
commit a9c3304c4e
10 changed files with 2031 additions and 279 deletions
@@ -0,0 +1,122 @@
+<!-- generated-by: gsd-doc-writer -->
+# Testing
+
+## Test framework and setup
+
+Both apps use **Vitest** (`^4.1.8`).
+
+| App | Environment | Setup file |
+|-----|-------------|------------|
+| `apps/api` | `node` | `apps/api/test/setup.ts` |
+| `apps/pwa` | `jsdom` | `apps/pwa/src/test-setup.ts` |
+
+**apps/api setup** (`test/setup.ts`) registers a global `afterEach` that truncates `list_items`, `list_shares`, `push_subscriptions`, and `lists` in FK-safe order after every test. This keeps DB-backed integration tests isolated without requiring a full DB reset between runs. Parallel file execution is disabled (`fileParallelism: false`) to prevent FK violations when multiple test files share the same MariaDB.
+
+**apps/pwa setup** (`src/test-setup.ts`) imports `@testing-library/jest-dom` for extended matchers and polyfills `window.matchMedia` for jsdom (required because Zustand's `calendarStore` calls `window.matchMedia` at module initialisation time). The timezone is pinned to `UTC` via `env: { TZ: 'UTC' }` so date-extraction assertions are deterministic across developer machines and CI.
+
+No additional install step is needed beyond the normal `pnpm install` at the repo root.
+
+## Running tests
+
+**All API tests (from repo root):**
+
+```bash
+pnpm --filter @familysync/api test
+```
+
+This is also the command run by `pnpm test` at the root.
+
+**All PWA tests:**
+
+```bash
+pnpm --filter @familysync/pwa test
+```
+
+**Watch mode (API):**
+
+```bash
+pnpm --filter @familysync/api test:watch
+```
+
+**Single test file:**
+
+```bash
+pnpm --filter @familysync/api exec vitest run tests/routes/lists.test.ts
+```
+
+**Type checking (separate from tests — required):**
+
+Vitest uses esbuild, which strips TypeScript types at runtime. A test run can pass while `tsc` reports errors. Always run type checks separately:
+
+```bash
+pnpm typecheck          # runs tsc --noEmit across both apps
+pnpm --filter @familysync/api typecheck
+pnpm --filter @familysync/pwa typecheck
+```
+
+## Integration tests requiring a real database
+
+Several API tests in `apps/api/tests/lib/` and `apps/api/tests/routes/` connect to the real dev MariaDB rather than mocking the DB layer. These tests require the dev Docker stack to be running with port 3306 exposed.
+
+**Start the dev stack:**
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d mariadb
+```
+
+**Set environment variables, then run:**
+
+```bash
+set -a; . ./.env; set +a
+export DB_HOST=127.0.0.1 DB_PORT=3306
+pnpm --filter @familysync/api test
+```
+
+DB-backed tests that require this setup include:
+
+- `apps/api/tests/lib/listAccess.test.ts` — `getAccessibleListIds` access-scope queries
+- `apps/api/tests/lib/listChangeDispatcher.test.ts` — list change dispatcher with real DB rows
+- `apps/api/tests/routes/lists.test.ts` — full lists API router (creates/deletes real rows)
+
+Pure-logic tests (e.g. `apps/api/tests/broker/expand.test.ts`, `apps/api/tests/lib/rank.test.ts`) do not require DB — the `afterEach` cleanup is a no-op when tables are empty or no DB connection is available.
+
+## Writing new tests
+
+### File naming and location
+
+| App | Convention | Example |
+|-----|------------|---------|
+| `apps/api` | `apps/api/tests/{category}/*.test.ts` | `apps/api/tests/routes/push.test.ts` |
+| `apps/pwa` | co-located `*.test.ts` / `*.test.tsx` | `src/components/AppNav.test.tsx` |
+
+Test categories for `apps/api`:
+
+- `apps/api/tests/auth/` — authentication middleware and session handling
+- `apps/api/tests/broker/` — CalDAV sync, outbox worker, event expansion, push dispatch
+- `apps/api/tests/lib/` — pure library functions and service logic
+- `apps/api/tests/routes/` — HTTP route integration tests
+- `apps/api/tests/health.test.ts` — health check endpoint
+- `apps/api/tests/fixtures/` — shared `.ics` fixture files and DB fixture helpers
+
+### Test helpers
+
+- `apps/api/tests/helpers/db.ts` — `createMockDb()` returns a Vitest mock of the Drizzle `db` singleton; also exports sample VEVENT strings (`SAMPLE_VEVENT_TIMED`, `SAMPLE_VEVENT_ALLDAY`, `SAMPLE_VEVENT_RECURRING_TIMED`, `SAMPLE_VEVENT_RECURRING_ALLDAY`) for broker tests.
+- `apps/api/tests/fixtures/*.ics` — Raw iCalendar fixture files for broker parsing tests (`allday-birthday.ics`, `exdate-series.ics`, `single-duration.ics`, `weekly-count3.ics`, `weekly-dst.ics`).
+- `apps/api/tests/fixtures/vapid.ts` — VAPID key fixture for push tests.
+- `apps/pwa/src/test-setup.ts` — Provides `matchMedia` polyfill and jest-dom matchers for all PWA tests automatically via `setupFiles`.
+
+For PWA component tests, use `@testing-library/react` (`^16.3.0`) render helpers. Import from `vitest` for assertions — `@testing-library/jest-dom` matchers are available globally via the setup file.
+
+## Coverage requirements
+
+No coverage thresholds are configured in either `vitest.config.ts`. There is no minimum coverage enforcement in CI.
+
+## CI integration
+
+No CI pipeline is configured in this repository. Tests are run manually by developers before opening pull requests against the self-hosted Gitea remote.
+
+The recommended pre-PR gate is:
+
+```bash
+pnpm test && pnpm typecheck
+```