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

# Dashboard Integration Tests

This directory contains integration tests for the dashboard functionality, following the Clean Integration Testing strategy defined in `plans/clean_integration_strategy.md`.

## Test Philosophy

These tests focus on **Use Case orchestration** and **business logic**, not UI rendering. They verify that:

1. **Use Cases correctly orchestrate** interactions between their Ports (Repositories, Event Publishers)
2. **Data flows correctly** from repositories through use cases to presenters
3. **Error handling works** at the business logic level
4. **In-Memory adapters** are used for speed and determinism

## Test Files

### 1. [`dashboard-use-cases.integration.test.ts`](dashboard-use-cases.integration.test.ts)
Tests the orchestration logic of dashboard-related Use Cases.

**Focus:** Use Case orchestration patterns
- GetDashboardUseCase: Retrieves driver statistics, upcoming races, standings, and activity
- Validates that Use Cases correctly interact with their Ports
- Tests success paths and edge cases

**Scenarios:**
- Driver with complete data
- New driver with no history
- Driver with many upcoming races (limited to 3)
- Driver in multiple championships
- Driver with recent activity sorted by timestamp
- Edge cases: no upcoming races, no championships, no activity
- Error cases: driver not found, invalid ID, repository errors

### 2. [`dashboard-data-flow.integration.test.ts`](dashboard-data-flow.integration.test.ts)
Tests the complete data flow from repositories to DTOs.

**Focus:** Data transformation and flow
- Repository → Use Case → Presenter → DTO
- Data validation and transformation
- DTO structure and formatting

**Scenarios:**
- Complete data flow for driver with all data
- Complete data flow for new driver with no data
- Data consistency across multiple calls
- Maximum upcoming races handling
- Many championship standings
- Many recent activities
- Mixed race statuses
- DTO structure validation

### 3. [`dashboard-error-handling.integration.test.ts`](dashboard-error-handling.integration.test.ts)
Tests error handling and edge cases at the Use Case level.

**Focus:** Error orchestration and handling
- Repository errors (driver not found, data access errors)
- Validation errors (invalid driver ID, invalid parameters)
- Business logic errors (permission denied, data inconsistencies)
- Error recovery and fallbacks

**Scenarios:**
- Driver not found errors
- Validation errors (empty, null, undefined, malformed IDs)
- Repository query errors (driver, race, league, activity)
- Event publisher error handling
- Business logic error handling (corrupted data, inconsistencies)
- Error recovery and fallbacks
- Error propagation
- Error logging and observability

## Directory Structure

```
tests/integration/dashboard/
├── dashboard-use-cases.integration.test.ts      # Use Case orchestration tests
├── dashboard-data-flow.integration.test.ts      # Data flow tests
├── dashboard-error-handling.integration.test.ts # Error handling tests
└── README.md                                    # This file
```

## Test Pattern

All tests follow the Clean Integration Test pattern:

```typescript
describe('Feature - Test Scenario', () => {
  let harness: IntegrationTestHarness;
  let inMemoryRepository: InMemoryRepository;
  let useCase: UseCase;

  beforeAll(() => {
    // Initialize In-Memory adapters
    // inMemoryRepository = new InMemoryRepository();
    // useCase = new UseCase({ repository: inMemoryRepository });
  });

  beforeEach(() => {
    // Clear In-Memory repositories
    // inMemoryRepository.clear();
  });

  it('should [expected behavior]', async () => {
    // TODO: Implement test
    // Given: Setup test data in In-Memory repositories
    // When: Execute the Use Case
    // Then: Verify orchestration (repository calls, event emissions)
    // And: Verify result structure and data
  });
});
```

## Key Principles

### 1. Use In-Memory Adapters
- All tests use In-Memory repositories for speed and determinism
- No external database or network dependencies
- Tests run in milliseconds

### 2. Focus on Orchestration
- Tests verify **what** the Use Case does, not **how** it does it
- Verify repository calls, event emissions, and data flow
- Don't test UI rendering or visual aspects

### 3. Zero Implementation
- These are **placeholders** with TODO comments
- No actual implementation logic
- Just the test framework and structure

### 4. Business Logic Only
- Tests are for business logic, not UI
- Focus on Use Case orchestration
- Verify data transformation and error handling

## Running Tests

```bash
# Run all dashboard integration tests
npm test -- tests/integration/dashboard/

# Run specific test file
npm test -- tests/integration/dashboard/dashboard-use-cases.integration.test.ts

# Run with verbose output
npm test -- tests/integration/dashboard/ --reporter=verbose
```

## Related Files

- [`plans/clean_integration_strategy.md`](../../../plans/clean_integration_strategy.md) - Clean Integration Testing strategy
- [`tests/e2e/bdd/dashboard/`](../../e2e/bdd/dashboard/) - BDD E2E tests (user outcomes)
- [`tests/integration/harness/`](../harness/) - Integration test harness
- [`tests/integration/league/`](../league/) - Example integration tests

## Observations

Based on the BDD E2E tests, the dashboard functionality requires integration test coverage for:

1. **Driver Statistics Calculation**
   - Rating, rank, starts, wins, podiums, leagues
   - Derived from race results and league participation

2. **Upcoming Race Management**
   - Retrieval of scheduled races
   - Limiting to 3 races
   - Sorting by scheduled date
   - Time-until-race calculation

3. **Championship Standings**
   - League participation tracking
   - Position and points calculation
   - Driver count per league

4. **Recent Activity Feed**
   - Activity type categorization (race_result, etc.)
   - Timestamp sorting (newest first)
   - Status assignment (success, info)

5. **Error Handling**
   - Driver not found scenarios
   - Invalid driver ID validation
   - Repository error propagation
   - Event publisher error handling

6. **Edge Cases**
   - New drivers with no data
   - Drivers with partial data
   - Maximum data limits (upcoming races)
   - Data inconsistencies

These integration tests will provide fast, deterministic verification of the dashboard business logic before UI implementation.