123 lines
5.0 KiB
Markdown
123 lines
5.0 KiB
Markdown
<!-- 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
|
|
```
|