Shared test infrastructure plan (Phase 5)

Goal: centralize all reusable test helpers (app factory, DB helpers, service accessors, auth flows) under a single tests/* namespace so any test file can import from @/tests/* instead of redefining or duplicating setup logic.

This is a Phase 5 task – design here now, implement when Phase 5 starts.

---

Target structure

Under apps/worker/src we will introduce a dedicated tests/ folder, separate from the existing test/ helpers (which are currently more ad‑hoc). Planned structure:

• tests/app.ts – single place to create the Hono app for tests
  • Wraps createTestApp(env) and any global middleware/config needed for routes
  • Exposes helpers like:
    • createTestContext() (env + app + common headers)
    • withAuth(requestInitOverrides?) to inject cookies / Authorization header
• tests/env.ts – test environment helpers
  • createTestEnv() – wrapper around createMockEnv() if still used, or a more realistic env when we move to a real DB
  • Central place to tweak env flags for tests (e.g. feature flags, log levels)
• tests/db.ts – DB utilities
  • Thin layer over the current mockDatabase / createDb
  • Provides:
    • resetDb() / seedDb() for integration tests
    • Type‑safe helpers to insert/find users, maintenance records, etc. for tests
• tests/auth.ts – shared auth flows
  • registerTestUser(role?: 'employee' | 'hod' | 'technician' | 'admin')
  • loginTestUser(email, password) – returns cookies / token and userId
  • createAuthSessionForRole(role) – registers + logs in + returns shared state
  • Designed so /me* tests, auth tests, and maintenance role‑flow tests all reuse the same helpers.
• tests/maintenance.ts – maintenance test helpers
  • Helpers to create/approve/assign/complete maintenance requests using the role‑aware auth helpers from tests/auth.ts.

All of these will be exported through an index:

• tests/index.ts
  • Re‑exports app, env, db, auth, maintenance helpers so tests can import:
    • import { createTestEnv, createTestApp } from '@/tests';
    • import { registerTestUser, loginTestUser } from '@/tests/auth';

---

Import path: @/tests/*

Goal: make all test utilities easy to discover and consistent to use.

• Update tsconfig path mapping so that:
  • @/tests → apps/worker/src/tests/index.ts
  • @/tests/* → apps/worker/src/tests/*
• Existing imports like @/test/app and @/test/setup will eventually be migrated to the new @/tests/* namespace once the shared infrastructure is ready.
• During migration we may temporarily keep both:
  • Old: @/test/* (legacy; to be removed)
  • New: @/tests/* (preferred, Phase 5+)

---

Phase 5 tasks (high‑level)

When Phase 5 starts, implement the following in order:

1. Create apps/worker/src/tests/ folder and base files
   • tests/app.ts, tests/env.ts, tests/db.ts, tests/auth.ts, tests/maintenance.ts, tests/index.ts (initial minimal versions).
2. Wire path aliases
   • Update tsconfig / Vitest config so @/tests/* resolves to apps/worker/src/tests/*.
3. Migrate route integration tests
   • Update auth-login.route.test.ts, me.route.test.ts, and new auth integration tests to use:
     • createTestEnv and createTestApp from @/tests.
4. Migrate service‑level tests where beneficial
   • Gradually replace direct createMockEnv / mockDatabase imports with @/tests/env and @/tests/db helpers.
5. Deprecate old test/ helpers
   • Once most tests are moved, mark apps/worker/src/test/* as legacy in docs, then either:
     • Inline any remaining unique helpers into tests/*, or
     • Remove unused files.

---

Relation to auth + maintenance integration plans

This shared tests/* infrastructure will be the home for:

• The auth integration helpers (real register + login + /me* + auth/account/delete), and
• The multi‑role maintenance integration helpers (employee creates, HOD approves, technician completes).

Those flows will consume:

• tests/app.ts for creating an app instance,
• tests/env.ts for a consistent test Env,
• tests/db.ts for any seeding/cleanup between flows,
• tests/auth.ts for creating and reusing logged‑in users by role.

Implementation is deferred to Phase 5; this document is the spec to follow when we get there.