231 lines
11 KiB
Markdown
231 lines
11 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
|
||
|
||
### Unit and integration 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 unit 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
|
||
```
|
||
|
||
### End-to-end tests (Playwright)
|
||
|
||
The PWA has a Playwright harness configured in `apps/pwa/playwright.config.ts` with two device profiles:
|
||
|
||
| Profile | Viewport | Engine | User-Agent |
|
||
| -------- | -------- | -------- | ------------------------- |
|
||
| `iphone` | 390×844 | WebKit | Mobile Safari (iPhone 14) |
|
||
| `pixel` | 412×915 | Chromium | Chrome Android (Pixel 7) |
|
||
|
||
Both profiles block the service worker (`serviceWorkers: 'block'`) so the Workbox SW does not intercept requests during tests. Auth is handled via `DEV_AUTH_BYPASS=true` on the API — never via stored browser state.
|
||
|
||
**Run all e2e tests (both profiles):**
|
||
|
||
```bash
|
||
pnpm test:e2e
|
||
# or
|
||
pnpm --filter @familysync/pwa test:e2e
|
||
```
|
||
|
||
**Run a single profile:**
|
||
|
||
```bash
|
||
pnpm --filter @familysync/pwa exec playwright test --project=pixel
|
||
pnpm --filter @familysync/pwa exec playwright test --project=iphone
|
||
```
|
||
|
||
**Interactive UI mode:**
|
||
|
||
```bash
|
||
pnpm --filter @familysync/pwa test:e2e:ui
|
||
```
|
||
|
||
The `baseURL` is driven by `PLAYWRIGHT_BASE_URL` (default: `http://localhost:5173`). In local mode the config reuses a running Vite dev server; in CI it starts Vite itself. The API, MariaDB, and Redis must already be running via Docker Compose before launching e2e tests locally — see `docs/DEVELOPMENT.md`.
|
||
|
||
### 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
|
||
```
|
||
|
||
The PWA typecheck also covers the e2e spec files: `tsc --project tsconfig.e2e.json --noEmit`.
|
||
|
||
## Quality gate
|
||
|
||
The full local quality gate before opening a PR:
|
||
|
||
```bash
|
||
pnpm lint && pnpm format:check && pnpm typecheck && pnpm test
|
||
```
|
||
|
||
Add e2e when changing PWA behaviour:
|
||
|
||
```bash
|
||
pnpm test:e2e
|
||
```
|
||
|
||
| Step | Command | What it checks |
|
||
| ---------------- | ------------------------------------ | -------------------------------------------------------- |
|
||
| Lint | `pnpm lint` | ESLint `--max-warnings 0` across both apps (type-aware) |
|
||
| Format check | `pnpm format:check` | Prettier — fails on any unformatted file |
|
||
| Typecheck | `pnpm typecheck` | `tsc --noEmit` across both apps (including e2e tsconfig) |
|
||
| Unit / API tests | `pnpm test` | API integration tests via Vitest |
|
||
| PWA unit tests | `pnpm --filter @familysync/pwa test` | Component and logic tests in jsdom |
|
||
| E2E | `pnpm test:e2e` | Playwright iphone + pixel profiles |
|
||
|
||
A deliberate ESLint violation makes `pnpm lint` exit non-zero; a formatting deviation makes `pnpm format:check` exit non-zero. Both block the PR in CI.
|
||
|
||
To auto-fix formatting locally:
|
||
|
||
```bash
|
||
pnpm format # prettier --write .
|
||
```
|
||
|
||
## 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` |
|
||
| `apps/pwa` | e2e specs | `e2e/*.spec.ts` |
|
||
|
||
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
|
||
|
||
CI runs on a self-hosted Gitea Actions runner and triggers on every pull request targeting `main` (`.gitea/workflows/ci.yml`). Three jobs run in parallel:
|
||
|
||
### `fast-checks`
|
||
|
||
Runs lint, format check, typecheck, and PWA unit tests — no external services required.
|
||
|
||
| Step | Command |
|
||
| -------------- | ------------------------------------ |
|
||
| Lint | `pnpm lint` |
|
||
| Format check | `pnpm format:check` |
|
||
| Typecheck | `pnpm typecheck` |
|
||
| PWA unit tests | `pnpm --filter @familysync/pwa test` |
|
||
|
||
### `api`
|
||
|
||
Runs the full API test suite against a `mariadb:11` service container.
|
||
|
||
| Step | Detail |
|
||
| ----------------- | ---------------------------------------------------------- |
|
||
| MariaDB service | `mariadb:11` container; `DB_HOST=mariadb`, `DB_PORT=3306` |
|
||
| Readiness poll | Node script via `mysql2` driver (no `mysql` CLI in runner) |
|
||
| Schema migrations | `pnpm --filter @familysync/api db:migrate` |
|
||
| Tests | `pnpm --filter @familysync/api test` |
|
||
|
||
The throwaway credentials (`DB_USER=familysync`, `DB_PASSWORD=testpass`) are scoped to the ephemeral CI container and are never production secrets.
|
||
|
||
`actions/cache@v4` is intentionally omitted — the cache server times out on this runner (socket hang-up). `pnpm install` without cache takes ~30 s and is acceptable.
|
||
|
||
### `harness`
|
||
|
||
Runs the Playwright mobile e2e harness (iphone + pixel) against a runner-hosted dev stack.
|
||
|
||
| Step | Detail |
|
||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| MariaDB service | Same `mariadb:11` setup as the `api` job |
|
||
| Schema migrations | `pnpm --filter @familysync/api db:migrate` |
|
||
| Dev user seed | Inserts `users` row id=1 (`INSERT IGNORE`) for `DEV_AUTH_BYPASS` |
|
||
| API build | `pnpm --filter @familysync/api build` (dist/ is gitignored) |
|
||
| Playwright install | `npx playwright install --with-deps webkit chromium` (no cache) |
|
||
| API start + tests | API started as a background process in the same step as `playwright test` to survive the step boundary; `DEV_AUTH_BYPASS=true`, `NODE_ENV=development` |
|
||
| Base URL | `http://127.0.0.1:5173` (not `localhost` — runner resolves `localhost` to `::1` but Vite binds IPv4-only) |
|
||
| Artifacts on fail | Traces, screenshots, videos, and HTML report uploaded via `ChristopherHX/gitea-upload-artifact@v4` (standard `upload-artifact` aborts on Gitea) |
|
||
|
||
The API process is started and the Playwright suite invoked within a single CI step. Starting the API in an earlier step causes it to be reaped at the step boundary before Playwright runs.
|