Testing

TutorTool has an E2E test pipeline built on Playwright, with a test-only backend daemon and fast SQLite DB reset.

Quick start

# 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:

Ask Claude to open http://127.0.0.1:<TT_TEST_PORT>/admin/login via Playwright MCP.
Log in with seed credentials: admin@tutortool.com / admin.
Drive the app interactively; take screenshots to verify UI.
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:

Install deps (Node 20 + pnpm + Rust 1.95)
Cache Cargo + pnpm store
cargo check + pnpm check (type checks)
cargo test (unit tests)
pnpm build (frontend build)
make test-up + pnpm test:e2e (E2E)
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.

2.7 KiB Raw Blame History Unescape Escape