# Leaderboards BDD E2E Tests

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

## Test Coverage

### 1. Global Leaderboards Page (`leaderboards-main.spec.ts`)
Tests the main leaderboards page at `/leaderboards` that displays:
- Global driver rankings (top performers)
- Global team rankings (top teams)
- Navigation to detailed driver/team leaderboards
- Leaderboard filtering and sorting options
- Leaderboard data accuracy and consistency

**Key Scenarios:**
- User sees global driver rankings
- User sees global team rankings
- User can navigate to detailed driver leaderboard
- User can navigate to detailed team leaderboard
- User can click on driver/team entries to view profiles
- Leaderboards display with consistent ranking order
- Leaderboards display with accurate data
- Leaderboards handle errors gracefully
- Leaderboards show loading states
- Leaderboards have proper SEO metadata
- Leaderboards are accessible

### 2. Driver Rankings Page (`leaderboards-drivers.spec.ts`)
Tests the detailed driver rankings page at `/leaderboards/drivers` that displays:
- Comprehensive list of all registered drivers
- Driver search and filtering functionality
- Driver sorting options (by rating, name, rank, etc.)
- Pagination for large driver lists
- Driver cards with detailed information
- Driver profile navigation

**Key Scenarios:**
- User sees a comprehensive list of all drivers
- User can search for drivers by name
- User can filter drivers by rating range
- User can filter drivers by team
- User can sort drivers by different criteria
- User sees pagination controls when there are many drivers
- User sees empty states when no drivers match search
- User sees empty states when no drivers exist
- User can clear search and filters
- User sees driver count information
- User sees driver cards with consistent information
- User can click on driver cards to view profiles
- User sees driver rankings with accurate data
- User sees driver rankings with proper error handling
- User sees driver rankings with loading states
- User sees driver rankings with SEO metadata
- User sees driver rankings with proper accessibility

### 3. Team Rankings Page (`leaderboards-teams.spec.ts`)
Tests the detailed team rankings page at `/leaderboards/teams` that displays:
- Comprehensive list of all registered teams
- Team search and filtering functionality
- Team sorting options (by rating, name, rank, member count, etc.)
- Pagination for large team lists
- Team cards with detailed information
- Team profile navigation

**Key Scenarios:**
- User sees a comprehensive list of all teams
- User can search for teams by name
- User can filter teams by rating range
- User can filter teams by member count
- User can sort teams by different criteria
- User sees pagination controls when there are many teams
- User sees empty states when no teams match search
- User sees empty states when no teams exist
- User can clear search and filters
- User sees team count information
- User sees team cards with consistent information
- User can click on team cards to view profiles
- User sees team rankings with accurate data
- User sees team rankings with proper error handling
- User sees team rankings with loading states
- User sees team rankings with SEO metadata
- User sees team rankings with proper accessibility

## Test Structure

All tests follow the BDD pattern:
- **Given**: Setup the initial state
- **When**: Perform the action
- **Then**: Verify the outcome

Each test file includes:
- Comprehensive test descriptions
- TODO comments indicating what needs to be implemented
- Proper Playwright test structure
- Focus on user outcomes, not visual implementation

## Implementation Notes

### What Needs to Be Implemented
Each test file contains TODO comments that need to be implemented:
1. Navigation setup in `beforeEach` hooks
2. Actual test logic for each scenario
3. Assertions to verify outcomes
4. Test data setup if needed

### Test Data Requirements
Tests may require:
- Registered drivers with various ratings and teams
- Registered teams with various ratings and member counts
- Searchable data for filtering tests
- Pagination data for large lists

### Environment Setup
Tests should run against:
- A running instance of the GridPilot website
- A database with test data
- The full stack (Docker containers)

## Running Tests

```bash
# Run all leaderboards tests
npx playwright test tests/e2e/bdd/leaderboards/

# Run specific test file
npx playwright test tests/e2e/bdd/leaderboards/leaderboards-main.spec.ts

# Run with UI
npx playwright test tests/e2e/bdd/leaderboards/ --ui
```

## Test Philosophy

These tests follow the BDD testing concept:
- **Focus on outcomes**: Tests validate what the user sees and can verify
- **Gherkin syntax**: Tests use Given/When/Then structure
- **User-centric**: Tests describe user journeys and acceptance criteria
- **Not visual**: Tests don't verify pixel-perfect implementation
- **End-to-end**: Tests validate the complete user flow

## Related Files

- [`plans/bdd_testing_concept.md`](../../../plans/bdd_testing_concept.md) - BDD testing philosophy and guidelines
- [`apps/website/app/leaderboards/`](../../../apps/website/app/leaderboards/) - Leaderboards implementation
- [`tests/e2e/bdd/`](../) - Other BDD E2E tests