gridpilot.gg/tests/e2e/onboarding/README.md

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

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

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

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

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:

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