# Onboarding Integration Tests

This directory contains integration tests for the GridPilot onboarding functionality.

## Overview

These tests verify the **orchestration logic** of onboarding Use Cases using **In-Memory adapters**. They focus on business logic interactions between Use Cases and their Ports (Repositories, Event Publishers, Services), not UI rendering.

## Testing Philosophy

Following the [Clean Integration Strategy](../../plans/clean_integration_strategy.md), these tests:

- **Focus on Use Case orchestration**: Verify that Use Cases correctly interact with their Ports
- **Use In-Memory adapters**: For speed and determinism
- **Test business logic only**: No UI testing
- **Verify orchestration patterns**: "Does the Use Case call the Repository and then the Event Publisher?"

## Test Files

### [`onboarding-wizard-use-cases.integration.test.ts`](onboarding-wizard-use-cases.integration.test.ts)
Tests the complete onboarding wizard orchestration:
- **CompleteOnboardingUseCase**: Orchestrates the entire onboarding flow
- **ValidatePersonalInfoUseCase**: Validates personal information
- **GenerateAvatarUseCase**: Generates racing avatar from face photo
- **SubmitOnboardingUseCase**: Submits completed onboarding data

**Scenarios covered:**
- Complete onboarding with valid data
- Validation of personal information
- Avatar generation with various parameters
- Error handling for invalid data
- Edge cases and boundary conditions

### [`onboarding-personal-info-use-cases.integration.test.ts`](onboarding-personal-info-use-cases.integration.test.ts)
Tests personal information-related Use Cases:
- **ValidatePersonalInfoUseCase**: Validates personal information
- **SavePersonalInfoUseCase**: Saves personal information to repository
- **UpdatePersonalInfoUseCase**: Updates existing personal information
- **GetPersonalInfoUseCase**: Retrieves personal information

**Scenarios covered:**
- Validation of personal information fields
- Saving personal information
- Updating personal information
- Retrieving personal information
- Error handling for invalid data
- Edge cases for display names, countries, and timezones

### [`onboarding-avatar-use-cases.integration.test.ts`](onboarding-avatar-use-cases.integration.test.ts)
Tests avatar-related Use Cases:
- **GenerateAvatarUseCase**: Generates racing avatar from face photo
- **ValidateAvatarUseCase**: Validates avatar generation parameters
- **SelectAvatarUseCase**: Selects an avatar from generated options
- **SaveAvatarUseCase**: Saves selected avatar to user profile
- **GetAvatarUseCase**: Retrieves user's avatar

**Scenarios covered:**
- Avatar generation with valid face photos
- Avatar generation with different suit colors
- Avatar selection from generated options
- Saving avatars to user profile
- Retrieving avatars
- Error handling for invalid files
- Edge cases for photo formats, dimensions, and content

### [`onboarding-validation-use-cases.integration.test.ts`](onboarding-validation-use-cases.integration.test.ts)
Tests validation-related Use Cases:
- **ValidatePersonalInfoUseCase**: Validates personal information
- **ValidateAvatarUseCase**: Validates avatar generation parameters
- **ValidateOnboardingUseCase**: Validates complete onboarding data
- **ValidateFileUploadUseCase**: Validates file upload parameters

**Scenarios covered:**
- Validation of personal information fields
- Validation of avatar generation parameters
- Validation of complete onboarding data
- Validation of file upload parameters
- Error handling for invalid data
- Edge cases for display names, timezones, countries, file sizes, and dimensions

## Test Structure

Each test file follows this pattern:

```typescript
import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
import { InMemoryUserRepository } from '../../../adapters/users/persistence/inmemory/InMemoryUserRepository';
import { InMemoryEventPublisher } from '../../../adapters/events/InMemoryEventPublisher';
import { InMemoryAvatarService } from '../../../adapters/media/inmemory/InMemoryAvatarService';

describe('Onboarding Use Case Orchestration', () => {
  let userRepository: InMemoryUserRepository;
  let eventPublisher: InMemoryEventPublisher;
  let avatarService: InMemoryAvatarService;

  beforeAll(() => {
    // TODO: Initialize In-Memory repositories, event publisher, and services
  });

  beforeEach(() => {
    // TODO: Clear all In-Memory repositories before each test
  });

  describe('Use Case - Success Path', () => {
    it('should perform action with valid data', async () => {
      // TODO: Implement test
      // Scenario: Description
      // Given: A new user exists
      // When: UseCase.execute() is called with valid data
      // Then: Expected outcome should occur
      // And: EventPublisher should emit appropriate event
    });
  });

  describe('Use Case - Validation', () => {
    it('should reject action with invalid data', async () => {
      // TODO: Implement test
      // Scenario: Description
      // Given: A new user exists
      // When: UseCase.execute() is called with invalid data
      // Then: Should throw appropriate error
      // And: EventPublisher should NOT emit event
    });
  });

  describe('Use Case - Error Handling', () => {
    it('should handle repository errors gracefully', async () => {
      // TODO: Implement test
      // Scenario: Repository error
      // Given: Repository throws an error
      // When: UseCase.execute() is called
      // Then: Should propagate the error appropriately
      // And: EventPublisher should NOT emit any events
    });
  });

  describe('Use Case - Edge Cases', () => {
    it('should handle edge case scenarios', async () => {
      // TODO: Implement test
      // Scenario: Edge case
      // Given: A new user exists
      // When: UseCase.execute() is called with edge case data
      // Then: Should handle appropriately
      // And: EventPublisher should emit appropriate events
    });
  });
});
```

## Key User Journeys Covered

### Driver Onboarding Journey
1. New user logs in for the first time
2. User completes personal information (Step 1)
3. User creates a racing avatar (Step 2)
4. User completes onboarding
5. User is redirected to dashboard

### Validation Journey
1. User attempts to proceed with invalid data
2. User sees validation errors
3. User corrects the data
4. User successfully proceeds

### Error Recovery Journey
1. User encounters a network error
2. User sees error message
3. User retries the operation
4. User successfully completes the operation

## In-Memory Adapters Used

- **InMemoryUserRepository**: Stores user data in memory
- **InMemoryEventPublisher**: Publishes events in memory
- **InMemoryAvatarService**: Generates avatars in memory

## Implementation Notes

- All tests are placeholders with TODO comments
- Tests should use Vitest's test and expect APIs
- Tests should focus on business logic orchestration
- Tests should be independent and isolated
- Tests should use proper setup and teardown
- Tests should handle both success and error scenarios

## Future Enhancements

- Add test data factories for consistent test data
- Add performance testing for avatar generation
- Add concurrent submission testing
- Add more edge case scenarios
- Add integration with real adapters (Postgres, S3, etc.)

## Related Documentation

- [Clean Integration Strategy](../../plans/clean_integration_strategy.md)
- [BDD E2E Tests](../../e2e/bdd/onboarding/)
- [Testing Layers](../../docs/TESTING_LAYERS.md)