docs: refresh CI + lint/format docs (Phase 8 + Phase 13)
This commit is contained in:
Lucas Berger
+114
-7
@@ -19,6 +19,8 @@ No additional install step is needed beyond the normal `pnpm install` at the rep
|
||||
|
||||
## Running tests
|
||||
|
||||
### Unit and integration tests
|
||||
|
||||
**All API tests (from repo root):**
|
||||
|
||||
```bash
|
||||
@@ -27,7 +29,7 @@ pnpm --filter @familysync/api test
|
||||
|
||||
This is also the command run by `pnpm test` at the root.
|
||||
|
||||
**All PWA tests:**
|
||||
**All PWA unit tests:**
|
||||
|
||||
```bash
|
||||
pnpm --filter @familysync/pwa test
|
||||
@@ -45,7 +47,41 @@ pnpm --filter @familysync/api test:watch
|
||||
pnpm --filter @familysync/api exec vitest run tests/routes/lists.test.ts
|
||||
```
|
||||
|
||||
**Type checking (separate from tests — required):**
|
||||
### 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:
|
||||
|
||||
@@ -55,6 +91,39 @@ 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.
|
||||
@@ -89,6 +158,7 @@ Pure-logic tests (e.g. `apps/api/tests/broker/expand.test.ts`, `apps/api/tests/l
|
||||
| ---------- | ------------------------------------- | ------------------------------------ |
|
||||
| `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`:
|
||||
|
||||
@@ -114,10 +184,47 @@ No coverage thresholds are configured in either `vitest.config.ts`. There is no
|
||||
|
||||
## 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.
|
||||
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:
|
||||
|
||||
The recommended pre-PR gate is:
|
||||
### `fast-checks`
|
||||
|
||||
```bash
|
||||
pnpm test && pnpm typecheck
|
||||
```
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user