Testing Guide — Workers Services

Scope: apps/worker/src/lib/services/. This guide defines the test folder structure, naming, and type-safety so tests stay consistent and maintainable.

Current session: Focus on non-maintenance tests only (auth, me, cache, storage, cookies, jwt, mailer, internal, system). Skip maintenance tests entirely — maintenance queries/mutations have unresolved type issues and are in an incomplete state. Stabilize maintenance micro-services before expanding maintenance tests (see maintainer/systems/maintenance.md).

---

1. Test folder structure

• Each service (auth, me, maintenance, cache, etc.) has a single __tests__ directory next to its source.
• One test file per micro-service (or logical unit):
  services/<service>/<micro>/index.ts (or file.ts) → services/<service>/__tests__/<micro>.test.ts.
• Main index.ts:
  Add services/<service>/__tests__/index.test.ts only if the main index has logic that needs tests (e.g. composition or delegation). Otherwise skip it or use it only to re-export/organize other tests if desired.

Examples

Service source	Test file
auth/index.ts	auth/__tests__/index.test.ts (optional)
auth/login/index.ts	auth/__tests__/login.test.ts
auth/logout/index.ts	auth/__tests__/logout.test.ts
auth/register/index.ts	auth/__tests__/register.test.ts
auth/profile/index.ts	auth/__tests__/profile.test.ts
auth/verify/index.ts	auth/__tests__/verify.test.ts (if added)
me/avatar/index.ts	me/__tests__/avatar.test.ts
me/profile/index.ts	me/__tests__/profile.test.ts
maintenance/queries/index.ts	maintenance/__tests__/queries.test.ts
maintenance/mutation/index.ts	maintenance/__tests__/mutation.test.ts
maintenance/attachment/index.ts	maintenance/__tests__/attachment.test.ts
maintenance/permissions/index.ts	maintenance/__tests__/permissions.test.ts
maintenance/validation/index.ts	maintenance/__tests__/validation.test.ts
cache/user/index.ts	cache/__tests__/user.test.ts (if added)
cache/maintenance/index.ts	cache/__tests__/maintenance.test.ts (if added)
storage/index.ts	storage/__tests__/storage.test.ts

Large services (auth, me, maintenance, cache) use the same rule: one test file per micro-service under that service’s __tests__/.

---

2. Type-safety in tests

• Use real types from @/types (or the project alias you use) so test data matches production.
• Avoid as any for domain objects; type mocks with proper interfaces or use satisfies / partial types where needed.
• Session/auth: Use SessionData, User (or PopulatedUser) from @/types/auth.
• Maintenance: Use types from @/types/maintenance (e.g. MaintenanceRequestData, MaintenanceQueryParams, MaintenanceListResponse) and @/types/database (e.g. PopulatedMaintenanceRequest) where applicable.
• Env/config: Use Env from @/types/app for env mocks; use real config shape or a small test-only type that matches the parts under test.
• Zod/schema: When testing validation, use the same Zod schemas or types as the service (e.g. from @/lib/services/zod/...) so schema changes are caught by tests.

Example (type-safe mock)

import type { SessionData } from '@/types/auth';
import type { Env } from '@/types/app';

const mockUser: SessionData = {
  jti: 'jti-123',
  userId: 'user-123',
  user: {
    id: 'user-123',
    name: 'Test User',
    email: '[email protected]',
    role: 'employee',
    departmentId: 'dept-123',
    // ... other required fields from @/types/auth
  },
  loginTime: new Date(),
  lastActivity: new Date(),
  expiresAt: new Date(Date.now() + 3600000),
  isActive: true,
  permissions: ['maintenance.read'],
  deviceInfo: undefined,
  ipAddress: '',
};

Use the same pattern for maintenance request mocks with PopulatedMaintenanceRequest or MaintenanceRequestData from @/types/maintenance / @/types/database.

---

3. Current vs missing tests (checklist)

Use this to drive “implement missing tests and update old ones.”

Auth (services/auth/__tests__/)

Test file	Status	Notes
auth.test.ts	✅ Exists	Consider aligning with index/composition if needed
login.test.ts	✅ Exists	Use Env and auth types from @/types
logout.test.ts	✅ Exists
register.test.ts	✅ Exists
profile.test.ts	✅ Exists
refresh.test.ts	✅ Exists
verify.test.ts	❌ Missing	Add if verify logic is non-trivial
index.test.ts	Optional	Only if main auth index has testable logic

Me (services/me/__tests__/)

Test file	Status	Notes
avatar.test.ts	❌ Missing	Avatar service (upload/get/delete, storage path)
profile.test.ts	❌ Missing
stats.test.ts	❌ Missing
settings.test.ts	❌ Missing
security.test.ts	❌ Missing
notifications.test.ts	❌ Missing
email.test.ts	❌ Missing
index.test.ts	Optional

Maintenance (services/maintenance/__tests__/) — skip this session

Test file	Status	Notes
queries.test.ts	✅ Exists	Do not update until queries/mutations are stable; then align with @/types/maintenance, @/types/database.
mutations.test.ts	✅ Exists	Same: fix after mutation types are stable.
permissions.test.ts	✅ Exists
validation.test.ts	✅ Exists
maintenance.test.ts	✅ Exists
attachment.test.ts	❌ Missing	Add in next session after maintenance services are stable.
core.test.ts	Optional	Next session if needed.
index.test.ts	Optional	Next session if needed.

Cache (services/cache/__tests__/)

Test file	Status	Notes
cache.test.ts	✅ Exists	General cache; consider per-subservice (user, session, maintenance) if they grow

Other services

Service	Test file	Status
storage	storage/__tests__/storage.test.ts	❌ Missing
init	init/__tests__/get.test.ts or init.test.ts	Optional (getters/mocks)
cookies	cookies/__tests__/cookies.test.ts	✅ Exists
jwt	jwt/__tests__/jwt.test.ts	✅ Exists
mailer	mailer/__tests__/mailer.test.ts	✅ Exists
internal	internal/__tests__/internal.test.ts	✅ Exists
system	system/__tests__/system.test.ts	✅ Exists

---

4. Summary

• Structure: One __tests__ per service; one *.test.ts per micro-service (and optional index.test.ts).
• Naming: services/<service>/<micro>/index.ts → services/<service>/__tests__/<micro>.test.ts.
• Types: Use @/types (auth, maintenance, database, app) and real config/schema; avoid as any for domain data.
• Attachments: Covered under maintenance as maintenance/__tests__/attachment.test.ts (attachment lives under maintenance/attachment).
• Priority: Add missing tests (me/*, maintenance/attachment, storage); then update existing tests to match new service APIs and type-safe mocks.
• Failure and resilience: Next layer — failure cases, permission escalation, invalid state transitions, partial failure recovery — belongs in worker integration tests as those surfaces stabilize.

This keeps the test suite aligned with the service layout (auth, me, maintenance, cache with their micro-services) and reduces type and refactor issues.