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

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

4.3 KiB Raw Blame History