# Onboarding BDD E2E Tests

This directory contains BDD (Behavior-Driven Development) E2E tests for the GridPilot onboarding flow.

## Overview

The onboarding flow guides new users through a two-step wizard process:

1. **Personal Information** - Collects user details (name, display name, country, timezone)
2. **Racing Avatar** - Generates an AI-powered racing avatar from a face photo

## Test Files

### [`onboarding-wizard.spec.ts`](onboarding-wizard.spec.ts)
Tests the complete onboarding wizard flow, including:
- User redirection after login
- Wizard structure and navigation
- Step progression and completion
- Help panel visibility
- Error states and retry logic
- Authentication and authorization flows

### [`onboarding-personal-info.spec.ts`](onboarding-personal-info.spec.ts)
Tests the personal information collection step, including:
- Form field visibility and interaction
- Input validation (required fields, length limits, character restrictions)
- Country and timezone selection
- Step navigation (next/back)
- Data persistence across steps
- Real-time validation feedback

### [`onboarding-avatar.spec.ts`](onboarding-avatar.spec.ts)
Tests the avatar creation step, including:
- Face photo upload and preview
- Suit color selection
- Avatar generation process
- Avatar selection from generated options
- File upload validation (format, size, dimensions)
- Generation error states and retry logic

### [`onboarding-validation.spec.ts`](onboarding-validation.spec.ts)
Tests validation rules and error handling throughout the flow:
- Form field validation (empty fields, invalid formats, length limits)
- File upload validation (corrupted files, wrong dimensions, inappropriate content)
- Network and server error handling
- Concurrent submission prevention
- Edge cases and boundary conditions

## Testing Philosophy

These tests follow the BDD E2E testing concept:

- **Focus on Outcomes**: Tests validate what the user sees and can verify, not visual implementation details
- **Gherkin Syntax**: Scenarios are described using Given/When/Then format
- **User-Centric**: Tests represent real user journeys and acceptance criteria
- **Placeholder Structure**: Each test file contains TODO comments indicating what needs to be implemented

## Test Structure

Each test file follows this pattern:

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

  test('User sees expected outcome', async ({ page }) => {
    // TODO: Implement test
    // Scenario: Description
    // Given I am in a specific state
    // When I perform an action
    // Then I should see a specific outcome
  });
});
```

## Key User Journeys Covered

### Driver Onboarding Journey
1. New user logs in for the first time
2. User is redirected to onboarding page
3. User completes personal information (Step 1)
4. User creates a racing avatar (Step 2)
5. User completes onboarding
6. User is redirected to dashboard

### Validation Journey
1. User attempts to proceed with invalid data
2. User sees validation errors
3. User corrects the data
4. User successfully proceeds

### Error Recovery Journey
1. User encounters a network error
2. User sees error message
3. User retries the operation
4. User successfully completes the operation

## Implementation Notes

- All tests are placeholders with TODO comments
- Tests should use Playwright's test and expect APIs
- Tests should focus on user-visible outcomes
- Tests should be independent and isolated
- Tests should use proper authentication setup
- Tests should handle both success and error scenarios

## Future Enhancements

- Add test data factories for consistent test data
- Add visual regression testing for critical UI elements
- Add performance testing for avatar generation
- Add accessibility testing for all interactive elements
- Add cross-browser compatibility testing