From 3d91017d78b594adf63f1010af6c3a47bbca1dd5 Mon Sep 17 00:00:00 2001
From: "s0wlz (Matthias Puchstein)" <matthias@puchstein.lu>
Date: Wed, 29 Apr 2026 04:25:24 +0200
Subject: [PATCH] docs: add docs/testing.md and refine gitignore (track project
 docs, ignore local reference)

---
 .gitignore      |  7 ++++-
 docs/testing.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+), 1 deletion(-)
 create mode 100644 docs/testing.md

diff --git a/.gitignore b/.gitignore
index c48f521..f7d7621 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,7 +2,12 @@
 .claude/
 .playwright-mcp/
 .worktrees/
-docs/
+# Downloaded local reference docs (not project docs)
+docs/crates/
+docs/rust/
+docs/svelte/
+docs/typescript/
+docs/vite/
 
 # Node
 node_modules/
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 0000000..ba557e3
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,79 @@
+# Testing
+
+TutorTool has an E2E test pipeline built on Playwright, with a test-only backend daemon and fast SQLite DB reset.
+
+## Quick start
+
+```bash
+# 1. Start the test backend (once per shell/worktree session)
+make test-up
+
+# 2. Run the E2E suite
+pnpm --dir frontend test:e2e
+
+# 3. Interactive UI mode (Playwright UI)
+pnpm --dir frontend test:e2e:ui
+
+# 4. Stop the backend when done
+make test-down
+```
+
+## Make targets
+
+| Command | What it does |
+|---|---|
+| `make test-up` | Build test DB (if missing), start backend on test port, wait for `/health` |
+| `make test-down` | Kill the test backend |
+| `make test-reset` | Reset DB to clean seed state via `POST /__test__/reset` (fast, ~10-50ms) |
+| `make test-rebuild` | Wipe and rebuild test DB from migrations + seed (use after migration changes) |
+| `make test-e2e` | `test-up` + `pnpm test:e2e` in one command |
+
+## Worktree isolation
+
+Each git worktree gets its own port and DB path — no collisions when running tests in parallel across branches.
+
+The port is deterministic: `3100 + hash(worktree_path) % 100`. Run `bash scripts/test-env.sh` to see yours:
+
+```
+[test-env] TT_TEST_PORT=3142 TT_TEST_DB=/path/to/worktree/data/test/attendance.db
+```
+
+Set `TT_TEST_PORT_RANDOM=1` to bind to an ephemeral port instead (used in CI).
+
+## MCP / interactive verification
+
+After `make test-up`:
+
+1. Ask Claude to open `http://127.0.0.1:<TT_TEST_PORT>/admin/login` via Playwright MCP.
+2. Log in with seed credentials: `admin@tutortool.com` / `admin`.
+3. Drive the app interactively; take screenshots to verify UI.
+4. Run `make test-reset` between scenarios to restore clean state.
+
+## DB reset mechanism
+
+The backend exposes `POST /__test__/reset` only when started with `TT_TEST_MODE=1`. The handler deletes all rows in FK-safe order and re-applies `backend/demo/demo_seed.sql` in a single transaction. It never exists in production (the route is not registered without the env flag).
+
+## Seed data
+
+| Resource | Value |
+|---|---|
+| Admin email | `admin@tutortool.com` |
+| Admin password | `admin` |
+| Course | Demo Course 101 (Summer 2026) |
+| Students | Alice Smith … Judy Martinez (10 students) |
+| Room | Room A (Small) |
+| Slot | demo123 (open, 08:00–18:00) |
+
+## CI
+
+The Gitea Actions workflow at `.gitea/workflows/test.yml` runs on every push to `main` and on PRs:
+
+1. Install deps (Node 20 + pnpm + Rust 1.95)
+2. Cache Cargo + pnpm store
+3. `cargo check` + `pnpm check` (type checks)
+4. `cargo test` (unit tests)
+5. `pnpm build` (frontend build)
+6. `make test-up` + `pnpm test:e2e` (E2E)
+7. Upload `frontend/test-results/` + `frontend/playwright-report/` as artifacts on failure
+
+CI sets `TT_TEST_PORT_RANDOM=1` so parallel runner jobs on the same host don't collide.