gridpilot.gg/tests/integration/onboarding/README.md

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, 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

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

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

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

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:

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
• BDD E2E Tests
• Testing Layers