# BDD E2E Testing Concept - GridPilot

## 1. Vision
Our BDD (Behavior-Driven Development) E2E tests serve as the **final source of truth** for the GridPilot platform. They define the "Final Expectations" by describing user journeys in plain English (Gherkin), ensuring that the core value proposition—automation and unified league management—is delivered.

We focus on **outcomes**, not visual implementation.

## 2. Core Scenarios (Gherkin)

### Feature: Driver Onboarding and League Participation
**Scenario: Driver joins a league and prepares for a race**
  Given I am a registered driver "John Doe"
  And I am on the "Leagues Discovery" page
  When I select the "European GT League"
  And I click "Join League"
  Then I should see myself in the "Roster"
  And the "Dashboard" should show the next race at "Monza"

### Feature: Admin League Management and Automation
**Scenario: Admin schedules a race via Companion and verifies on Website**
  Given I am a league admin for "European GT League"
  When the Companion App schedules a "GT3 Monza" race
  Then the Website "Schedule" page should display the "Monza" race
  And drivers should be able to "Register" for this race

### Feature: Results and Standings
**Scenario: Admin imports results and standings update automatically**
  Given a completed race "Monza GP" exists in "European GT League"
  And I am an admin on the "Import Results" page
  When I upload the iRacing results CSV
  Then the "Race Results" page should show "John Doe" in P1
  And the "Standings" should reflect the new points for "John Doe"

## 3. Testing Hierarchy & Cleanup

### Layer 1: Unit Tests (STAY)
- **Location:** Adjacent to code (`*.test.ts`)
- **Focus:** Domain logic, value objects, pure business rules.
- **Status:** Keep as is. They are fast and catch logic errors early.

### Layer 2: Integration Tests (REFACTOR/REDUCE)
- **Location:** `tests/integration/`
- **Focus:** Adapter wiring and Use Case orchestration.
- **Cleanup:** Many integration tests that currently "smoke test" UI data flows (e.g., `standings-data-flow.integration.test.ts`) will be superseded by BDD E2E tests. We will keep only those that test complex infrastructure boundaries (e.g., Database constraints, external API adapters).

### Layer 3: BDD E2E Tests (NEW CORE)
- **Location:** `tests/e2e/bdd/` (using Playwright)
- **Focus:** Final outcome validation.
- **Status:** These become the primary "Acceptance Tests".

## 4. Obsolete and Redundant Tests Audit

Based on the new BDD E2E focus, the following tests are candidates for removal or refactoring:

### E2E Layer
- `tests/e2e/website/league-pages.e2e.test.ts`: **Refactor**. This file contains many "Verify X is visible" tests. These should be absorbed into the BDD scenarios (e.g., "Then I should see the Monza race").
- `tests/e2e/website/route-coverage.e2e.test.ts`: **Keep**. This is a technical smoke test ensuring no 404s, which is different from behavioral testing.

### Integration Layer
- `tests/integration/league/standings-data-flow.integration.test.ts`: **Obsolete**. The BDD scenario "Admin imports results and standings update" covers this end-to-end.
- `tests/integration/league/schedule-data-flow.integration.test.ts`: **Obsolete**. Covered by the "Admin schedules a race" BDD scenario.
- `tests/integration/league/stats-data-flow.integration.test.ts`: **Obsolete**. Should be part of the "Results and Standings" BDD feature.
- `tests/integration/database/*`: **Keep**. These ensure data integrity at the persistence layer, which E2E tests might miss (e.g., unique constraints).

## 5. Testing Hierarchy

| Layer | Tool | Responsibility | Data |
|-------|------|----------------|------|
| **Unit** | Vitest | Business Rules / Domain Invariants | Mocks / In-memory |
| **Integration** | Vitest | Infrastructure Boundaries (DB, API Contracts) | In-memory / Docker DB |
| **BDD E2E** | Playwright | Final User Outcomes / Acceptance Criteria | Full Stack (Docker) |

## 6. Implementation Plan

1. **Infrastructure Setup:** Configure Playwright to support Gherkin-style reporting or use a lightweight wrapper.
2. **Scenario Implementation:**
   - Implement "Driver Journey" (Discovery -> Join -> Dashboard).
   - Implement "Admin Journey" (Schedule -> Import -> Standings).
3. **Cleanup:**
   - Migrate logic from `league-pages.e2e.test.ts` to BDD steps.
   - Remove redundant `*-data-flow.integration.test.ts` files.
