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. Use a dedicated next session to stabilize maintenance micro-services and then add/run maintenance tests; see Next Session: Maintenance Stabilization.

---

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 this session. After stabilizing queries/mutations (see Next Session: Maintenance), align with @/types/maintenance, @/types/database.
mutations.test.ts	✅ Exists	Same: fix in next session 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: For the next layer (failure cases, permission escalation, invalid state transitions, partial failure recovery), see Failure tests plan.

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