This directory contains integration tests for the GridPilot Rating system, following the clean integration strategy defined in plans/clean_integration_strategy.md.

Testing Philosophy

These tests focus on Use Case orchestration - verifying that Use Cases correctly interact with their Ports (Repositories, Event Publishers, etc.) using In-Memory adapters for fast, deterministic testing.

Key Principles

Business Logic Only: Tests verify business logic orchestration, NOT UI rendering
In-Memory Adapters: Use In-Memory adapters for speed and determinism
Zero Implementation: These are placeholders - no actual test logic implemented
Use Case Focus: Tests verify Use Case interactions with Ports
Orchestration Patterns: Tests follow Given/When/Then patterns for business logic

Test Files

Core Rating Functionality

rating-calculation-use-cases.integration.test.ts
- Tests for rating calculation use cases
- Covers: CalculateRatingUseCase, UpdateRatingUseCase, GetRatingUseCase, etc.
- Focus: Verifies rating calculation logic with In-Memory adapters
rating-persistence-use-cases.integration.test.ts
- Tests for rating persistence use cases
- Covers: SaveRatingUseCase, GetRatingHistoryUseCase, GetRatingTrendUseCase, etc.
- Focus: Verifies rating data persistence and retrieval
rating-leaderboard-use-cases.integration.test.ts
- Tests for rating-based leaderboard use cases
- Covers: GetRatingLeaderboardUseCase, GetRatingPercentileUseCase, GetRatingComparisonUseCase, etc.
- Focus: Verifies leaderboard orchestration with In-Memory adapters

Advanced Rating Functionality

rating-team-contribution-use-cases.integration.test.ts
- Tests for team contribution rating use cases
- Covers: CalculateTeamContributionUseCase, GetTeamRatingUseCase, GetTeamContributionBreakdownUseCase, etc.
- Focus: Verifies team rating logic and contribution calculations
rating-consistency-use-cases.integration.test.ts
- Tests for consistency rating use cases
- Covers: CalculateConsistencyUseCase, GetConsistencyScoreUseCase, GetConsistencyTrendUseCase, etc.
- Focus: Verifies consistency calculation logic
rating-reliability-use-cases.integration.test.ts
- Tests for reliability rating use cases
- Covers: CalculateReliabilityUseCase, GetReliabilityScoreUseCase, GetReliabilityTrendUseCase, etc.
- Focus: Verifies reliability calculation logic (attendance, DNFs, DNSs)

Test Structure

Each test file follows the same structure:

describe('Use Case Orchestration', () => {
  let repositories: InMemoryAdapters;
  let useCase: UseCase;
  let eventPublisher: InMemoryEventPublisher;

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

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

  describe('UseCase - Success Path', () => {
    it('should [expected outcome]', async () => {
      // TODO: Implement test
      // Scenario: [description]
      // Given: [setup]
      // When: [action]
      // Then: [expected result]
      // And: [event emission]
    });
  });

  describe('UseCase - Edge Cases', () => {
    it('should handle [edge case]', async () => {
      // TODO: Implement test
      // Scenario: [description]
      // Given: [setup]
      // When: [action]
      // Then: [expected result]
      // And: [event emission]
    });
  });

  describe('UseCase - Error Handling', () => {
    it('should handle [error case]', async () => {
      // TODO: Implement test
      // Scenario: [description]
      // Given: [setup]
      // When: [action]
      // Then: [expected error]
      // And: [event emission]
    });
  });

  describe('UseCase - Data Orchestration', () => {
    it('should correctly format [data type]', async () => {
      // TODO: Implement test
      // Scenario: [description]
      // Given: [setup]
      // When: [action]
      // Then: [expected data format]
    });
  });
});

Implementation Guidelines

When Implementing Tests

Initialize In-Memory Adapters:

repository = new InMemoryRatingRepository();
eventPublisher = new InMemoryEventPublisher();
useCase = new UseCase({ repository, eventPublisher });

Clear Repositories Before Each Test:

beforeEach(() => {
  repository.clear();
  eventPublisher.clear();
});

Test Orchestration:
- Verify Use Case calls the correct repository methods
- Verify Use Case publishes correct events
- Verify Use Case returns correct data structure
- Verify Use Case handles errors appropriately
Test Data Format:
- Verify rating is calculated correctly
- Verify rating breakdown is accurate
- Verify rating updates are applied correctly
- Verify rating history is maintained

Example Implementation

it('should calculate rating after race completion', async () => {
  // Given: A driver with baseline rating
  const driver = Driver.create({ id: 'd1', iracingId: '100', name: 'John Doe', country: 'US' });
  await driverRepository.create(driver);

  // Given: A completed race with results
  const race = Race.create({
    id: 'r1',
    leagueId: 'l1',
    scheduledAt: new Date(Date.now() - 86400000),
    track: 'Spa',
    car: 'GT3',
    status: 'completed'
  });
  await raceRepository.create(race);

  const result = Result.create({
    id: 'res1',
    raceId: 'r1',
    driverId: 'd1',
    position: 1,
    lapsCompleted: 20,
    totalTime: 3600,
    fastestLap: 105,
    points: 25,
    incidents: 0,
    startPosition: 1
  });
  await resultRepository.create(result);

  // When: CalculateRatingUseCase.execute() is called
  const ratingResult = await calculateRatingUseCase.execute({
    driverId: 'd1',
    raceId: 'r1'
  });

  // Then: The rating should be calculated
  expect(ratingResult.isOk()).toBe(true);
  const rating = ratingResult.unwrap();
  expect(rating.driverId.toString()).toBe('d1');
  expect(rating.rating).toBeGreaterThan(0);
  expect(rating.components).toBeDefined();
  expect(rating.components.resultsStrength).toBeGreaterThan(0);
  expect(rating.components.consistency).toBeGreaterThan(0);
  expect(rating.components.cleanDriving).toBeGreaterThan(0);
  expect(rating.components.racecraft).toBeGreaterThan(0);
  expect(rating.components.reliability).toBeGreaterThan(0);
  expect(rating.components.teamContribution).toBeGreaterThan(0);

  // And: EventPublisher should emit RatingCalculatedEvent
  expect(eventPublisher.events).toContainEqual(
    expect.objectContaining({ type: 'RatingCalculatedEvent' })
  );
});

Observations

Based on the concept documentation, the rating system is complex with many components:

Rating Components: Results Strength, Consistency, Clean Driving, Racecraft, Reliability, Team Contribution
Calculation Logic: Weighted scoring based on multiple factors
Persistence: Rating history and trend tracking
Leaderboards: Rating-based rankings and comparisons
Team Integration: Team contribution scoring
Transparency: Clear explanation of rating changes

Each test file contains comprehensive test scenarios covering:

Success paths
Edge cases (small fields, DNFs, DNSs, penalties)
Error handling
Data orchestration patterns
Calculation accuracy
Persistence verification

Next Steps

Implement Test Logic: Replace TODO comments with actual test implementations
Add In-Memory Adapters: Create In-Memory adapters for all required repositories
Create Use Cases: Implement the Use Cases referenced in the tests
Create Ports: Implement the Ports (Repositories, Event Publishers, etc.)
Run Tests: Execute tests to verify Use Case orchestration
Refine Tests: Update tests based on actual implementation details

README.md

Rating Integration Tests