gridpilot.gg/apps/website/tests/services/auth/README.md

Auth Service Tests

Directory Structure

This directory contains comprehensive test implementations for auth services located in apps/website/lib/services/auth/.

Auth Services

The auth services are located in:

• apps/website/lib/services/auth/AuthService.ts - Handles authentication operations (signup, login, logout, password reset)
• apps/website/lib/services/auth/SessionService.ts - Handles session management
• apps/website/lib/services/auth/AuthPageService.ts - Processes URL parameters for auth pages

Test Files

The following comprehensive test files have been implemented:

AuthService.test.ts

Tests for authentication operations:

• Happy paths: Successful signup, login, logout, forgot password, reset password, and session retrieval
• Failure modes:
  • Validation errors (invalid email, weak password)
  • Authentication errors (invalid credentials, account locked)
  • Server errors (internal server errors, network errors)
  • Rate limiting errors
  • Token validation errors
• Decision branches:
  • Different user data structures
  • Different email formats
  • Different token formats
  • Different response formats
  • Empty display names
  • Special characters in display names
• Aggregation logic: Proper aggregation of API responses into SessionViewModel

SessionService.test.ts

Tests for session management:

• Happy paths: Successful session retrieval, null session handling
• Failure modes:
  • Server errors
  • Network errors
  • Authentication errors
  • Timeout errors
  • Unexpected error types
• Decision branches:
  • Different user data structures
  • Different email formats
  • Different token formats
  • Special characters in display names
  • Empty user data
  • Missing token
• Aggregation logic: Proper aggregation of session data into SessionViewModel

AuthPageService.test.ts

Tests for auth page parameter processing:

• Happy paths:
  • Login page parameter processing
  • Forgot password page parameter processing
  • Reset password page parameter processing
  • Signup page parameter processing
• Failure modes:
  • Missing reset token validation
  • Empty token validation
  • Null token validation
• Decision branches:
  • Different returnTo paths
  • Different token formats
  • Special characters in paths
  • Null/undefined/empty returnTo values
  • Different returnTo values and hasInsufficientPermissions combinations
• Aggregation logic: Proper aggregation of page parameters into DTOs

Test Coverage Summary

The comprehensive test suite covers:

Happy Paths ✓

• Successful authentication operations (signup, login, logout)
• Successful password reset flow (forgot password, reset password)
• Successful session retrieval
• Successful page parameter processing

Failure Modes ✓

• Validation errors (invalid email, weak password, missing token)
• Authentication errors (invalid credentials, account locked)
• Server errors (internal server errors)
• Network errors
• Rate limiting errors
• Timeout errors
• Unexpected error types

Retries ✓

• Not applicable for these services (no retry logic implemented)

Fallback Logic ✓

• Not applicable for these services (no fallback logic implemented)

Aggregation Logic ✓

• Proper aggregation of API responses into SessionViewModel
• Proper aggregation of page parameters into DTOs
• Handling of empty/missing data
• Default value handling

Decision Branches ✓

• Different user data structures
• Different email formats
• Different token formats
• Different returnTo paths
• Special characters in paths and display names
• Null/undefined/empty values
• Different response formats
• Different status values

Running Tests

Run the auth service tests using vitest:

# Run all tests
npm run test

# Run only auth service tests
npm run test -- apps/website/tests/services/auth

# Run with coverage
npm run test -- --coverage

# Run in watch mode
npm run test -- --watch

Test Structure

Each test file follows a consistent structure:

• describe blocks: Organized by service method
• happy paths: Successful operations
• failure modes: Error handling scenarios
• decision branches: Different input variations
• aggregation logic: Data aggregation and transformation
• error handling: Unexpected error scenarios

Mocking Strategy

All tests use mocked API clients:

• AuthApiClient is mocked to simulate API responses
• Mocks are created using Vitest's vi.fn()
• Each test has isolated mocks via beforeEach()
• Mocks simulate both success and failure scenarios

Dependencies

The tests use:

• Vitest for test framework
• TypeScript for type safety
• Mocked dependencies for isolation
• No external API calls (all mocked)