# Races BDD E2E Tests

This directory contains BDD (Behavior-Driven Development) E2E tests for the races functionality in GridPilot.

## Test Coverage

### races-main.spec.ts
Tests for the main races page (`/races`) that displays:
- Upcoming races (next race preview)
- Recent race results
- Race navigation and filtering

**Key Scenarios:**
- Driver sees upcoming races on main races page
- Driver sees recent race results on main races page
- Driver can navigate to race detail from upcoming/recent races
- Driver can navigate to all races page
- Driver sees race track name, date, time, car, and league for upcoming races
- Driver sees race track name, date, winner, car, and league for recent race results
- Driver sees empty states when no races exist
- Driver sees loading and error states

### races-all.spec.ts
Tests for the all races page (`/races/all`) that displays:
- Comprehensive list of all races
- Race filtering and sorting
- Race search functionality
- Pagination

**Key Scenarios:**
- Driver sees comprehensive list of all races
- Driver can navigate to race detail from all races list
- Driver sees race track name, date, car, league, and winner in list
- Driver can filter races by league, car, track, and date range
- Driver can search races by track name and league name
- Driver can sort races by date, league, and car
- Driver sees pagination controls and can navigate pages
- Driver sees empty states when no races match filters
- Driver sees loading and error states
- Driver can clear all filters

### race-detail.spec.ts
Tests for the race detail page (`/races/[id]`) that displays:
- Race information (track, car, league, date, time, duration, status)
- Race participants count
- Race winner and podium (for completed races)
- Race track layout, weather, and conditions
- Race statistics (lap count, incidents, penalties, protests, stewarding actions)
- Race lap times (average, fastest, best sectors)
- Race qualifying results and starting grid
- Race points distribution and championship implications
- Race highlights, video link, and gallery
- Race description, rules, and requirements

**Key Scenarios:**
- Driver sees race track name, car, league, date, time, and duration
- Driver sees race status (Upcoming, In Progress, Completed)
- Driver sees race participants count
- Driver sees race winner and podium for completed races
- Driver sees race track layout, weather, and conditions
- Driver sees race statistics (lap count, incidents, penalties, protests, stewarding actions)
- Driver sees race lap times (average, fastest, best sectors)
- Driver sees race qualifying results and starting grid
- Driver sees race points distribution and championship implications
- Driver sees race highlights, video link, and gallery
- Driver sees race description, rules, and requirements
- Driver can navigate to race results and stewarding pages
- Driver sees page title and description
- Driver sees loading and error states
- Driver sees 404 when race does not exist

### race-results.spec.ts
Tests for the race results page (`/races/[id]/results`) that displays:
- Complete race results (all finishers)
- Race statistics (fastest lap, average lap time, etc.)
- Race penalties and incidents
- Race stewarding actions
- Race points distribution

**Key Scenarios:**
- Driver sees complete race results on results page
- Driver sees race winner and podium on results page
- Driver sees driver name, team, car, position, race time, gap to leader, gap to previous, laps completed, points earned, fastest lap, average lap time, penalties, incidents, stewarding actions, and protests
- Driver sees race statistics (fastest lap, average lap time, total incidents, total penalties, total protests, total stewarding actions)
- Driver sees race points distribution and championship implications
- Driver can navigate to driver profile, team profile, race stewarding, and race detail pages
- Driver sees page title and description
- Driver sees loading and error states
- Driver sees empty state when no results available
- Driver sees 404 when race results do not exist

### race-stewarding.spec.ts
Tests for the race stewarding page (`/races/[id]/stewarding`) that displays:
- Pending protests
- Resolved protests
- Penalties issued
- Stewarding actions
- Stewarding statistics

**Key Scenarios:**
- Driver sees pending protests on stewarding page
- Driver sees resolved protests on stewarding page
- Driver sees penalties issued on stewarding page
- Driver sees stewarding actions on stewarding page
- Driver sees protest ID, type, status, submitter, respondent, description, evidence, and timestamp
- Driver sees penalty ID, type, severity, recipient, reason, and timestamp
- Driver sees stewarding action ID, type, recipient, reason, and timestamp
- Driver sees stewarding statistics (total protests, pending protests, resolved protests, total penalties, total stewarding actions, average protest resolution time, average penalty appeal success rate, average protest success rate, average stewarding action success rate)
- Driver can navigate to protest detail, penalty detail, stewarding action detail, race detail, and race results pages
- Driver sees page title and description
- Driver sees loading and error states
- Driver sees empty state when no stewarding data available
- Driver sees 404 when race stewarding does not exist

## Test Philosophy

These tests follow the BDD E2E testing concept defined in [`plans/bdd_testing_concept.md`](../../plans/bdd_testing_concept.md):

- **Focus on outcomes, not visual implementation**: Tests validate what the user sees and can verify, not how it's rendered
- **Use Gherkin syntax**: Tests are written in Given/When/Then format
- **Validate final user outcomes**: Tests serve as acceptance criteria for the races functionality
- **Use Playwright**: Tests are implemented using Playwright for browser automation

## Test Structure

Each test file follows this pattern:

```typescript
import { test, expect } from '@playwright/test';

test.describe('Feature Name', () => {
  test.beforeEach(async ({ page }) => {
    // TODO: Implement authentication setup
  });

  test('Driver sees [feature] on [page]', async ({ page }) => {
    // TODO: Implement test
    // Scenario: Driver views [feature]
    // Given I am a registered driver "John Doe"
    // And I am on the [page]
    // Then I should see [expected outcome]
  });
});
```

## TODO Implementation

All tests are currently placeholders with TODO comments. The actual test implementation should:

1. Set up authentication (login as a test driver)
2. Navigate to the appropriate page
3. Verify the expected outcomes using Playwright assertions
4. Handle loading states, error states, and edge cases
5. Use test data that matches the expected behavior

## Test Data

Tests should use realistic test data that matches the expected behavior:
- Driver: "John Doe" or similar test driver
- League: "European GT League" or similar test league
- Track: "Monza" or similar test track
- Car: "GT3" or similar test car
- Race: Completed races, upcoming races, races with results, races with stewarding data

## Future Enhancements

- Add test data factories/fixtures for consistent test data
- Add helper functions for common actions (login, navigation, etc.)
- Add visual regression tests for key UI components
- Add performance tests for race data loading
- Add accessibility tests for race pages
