blackcanyontickets/reactrebuild0825/tests/BULLETPROOF_AUTH_TESTS.md

# Bulletproof Authentication Tests

This document describes the comprehensive authentication test suite designed to validate the robustness, security, and performance of the Black Canyon Tickets authentication system.

## Overview

The bulletproof authentication test suite (`auth-bulletproof.spec.ts`) provides comprehensive end-to-end validation of the authentication system with focus on:

- **No Infinite Loops**: Ensures authentication flows complete successfully without hanging
- **Performance Benchmarks**: Validates auth operations meet strict timing requirements
- **Role-Based Access Control**: Tests all user roles and permission combinations
- **Session Management**: Validates session persistence and cleanup
- **Error Handling**: Tests graceful handling of edge cases and failures
- **Security**: Prevents authentication bypass and handles malicious inputs

## Test Categories

### 1. Authentication Flow - Core Functionality

**Purpose**: Validate the basic authentication workflow works correctly without infinite loops.

**Tests**:
- ✅ Complete login flow without infinite loops
- ✅ Prevent access to protected routes when not authenticated  
- ✅ Redirect to intended route after login
- ✅ Handle logout correctly and clear session

**Key Validations**:
- Login completes within 3 seconds (including mock API delay)
- Protected routes redirect to login when unauthenticated
- Post-login redirect to originally requested page works
- Logout clears all session data and redirects properly

### 2. Role-Based Access Control (RBAC)

**Purpose**: Ensure all user roles have correct access permissions.

**User Roles Tested**:
- `superadmin`: Full platform access
- `admin`: Organization-level administration  
- `organizer`: Event management capabilities
- `territoryManager`: Territory-specific management
- `staff`: Basic event and ticket access

**Protected Routes Tested**:
- `/dashboard` - All authenticated users
- `/events` - All authenticated users
- `/tickets` - All authenticated users
- `/customers` - All authenticated users
- `/analytics` - All authenticated users
- `/settings` - All authenticated users
- `/events/:id` - Staff+ roles only
- `/events/:id/gate-ops` - Staff+ roles only
- `/scan` - Staff+ roles only
- `/org/:id/payments` - OrgAdmin+ roles only
- `/org/:id/branding` - OrgAdmin+ roles only
- `/admin/*` - Superadmin only

**Key Validations**:
- Each role can access appropriate routes
- Each role is blocked from unauthorized routes
- Role switching works correctly
- 403 errors shown for insufficient permissions

### 3. Session Persistence

**Purpose**: Validate session management across browser interactions.

**Tests**:
- ✅ Persist session across page reloads when "remember me" enabled
- ✅ Do not persist session when "remember me" disabled
- ✅ Handle session restoration performance (< 1 second)
- ✅ Handle multiple rapid page refreshes without race conditions

**Key Validations**:
- Remember Me checkbox controls session persistence
- Session restoration is fast (< 1 second)
- Multiple rapid refreshes don't break authentication
- Browser context changes respect session settings

### 4. Error Handling and Edge Cases

**Purpose**: Ensure graceful handling of various failure scenarios.

**Tests**:
- ✅ Handle invalid credentials gracefully
- ✅ Handle empty form submission
- ✅ Handle network/API errors gracefully
- ✅ Handle concurrent login attempts
- ✅ Prevent multiple rapid login attempts

**Key Validations**:
- Clear error messages for invalid credentials
- Form validation prevents empty submissions
- Network failures show appropriate error messages
- Concurrent logins work correctly
- Button disabled state prevents duplicate submissions

### 5. Performance Benchmarks

**Purpose**: Ensure authentication operations meet strict performance requirements.

**Performance Thresholds**:
- Login: < 3 seconds (includes mock API delay)
- Logout: < 1 second  
- Route Navigation: < 2 seconds
- Session Restore: < 1 second

**Tests**:
- ✅ Meet all authentication performance thresholds
- ✅ Handle auth state under load conditions
- ✅ Concurrent authentication operations

**Key Validations**:
- All operations complete within defined thresholds
- Performance remains consistent under concurrent load
- No performance degradation with multiple users

### 6. Security and Edge Cases

**Purpose**: Prevent authentication bypass and handle malicious scenarios.

**Tests**:
- ✅ Prevent authentication bypass attempts
- ✅ Handle malformed localStorage data
- ✅ Handle browser back/forward buttons correctly

**Key Validations**:
- Direct localStorage manipulation doesn't bypass auth
- Malformed session data is handled gracefully
- Browser navigation maintains security after logout
- Session cleanup prevents unauthorized access

## Test Accounts

The tests use predefined mock accounts for different roles:

```typescript
const TEST_ACCOUNTS = {
  superadmin: { 
    email: 'superadmin@example.com', 
    password: 'password123',
    expectedName: 'Alex SuperAdmin',
    role: 'superadmin'
  },
  admin: { 
    email: 'admin@example.com', 
    password: 'password123',
    expectedName: 'Sarah Admin',
    role: 'admin'
  },
  organizer: { 
    email: 'organizer@example.com', 
    password: 'password123',
    expectedName: 'John Organizer',
    role: 'organizer'
  },
  territoryManager: { 
    email: 'territory@example.com', 
    password: 'password123',
    expectedName: 'Mike Territory',
    role: 'territoryManager'
  },
  staff: { 
    email: 'staff@example.com', 
    password: 'password123',
    expectedName: 'Emma Staff',
    role: 'staff'
  }
};
```

## Running the Tests

### Basic Test Execution

```bash
# Run all bulletproof auth tests
npm run test:auth:bulletproof

# Run with visible browser (headed mode)
npm run test:auth:bulletproof:headed

# Run with Playwright UI for debugging
npm run test:auth:bulletproof:ui
```

### Advanced Test Options

```bash
# Run specific test category
npx playwright test tests/auth-bulletproof.spec.ts --grep "Core Functionality"

# Run with specific browser
npx playwright test tests/auth-bulletproof.spec.ts --project=chromium

# Run with debug output
npx playwright test tests/auth-bulletproof.spec.ts --debug

# Generate and view HTML report
npx playwright test tests/auth-bulletproof.spec.ts --reporter=html
npx playwright show-report
```

## Screenshot Documentation

All tests automatically generate screenshots at key points:

- **Location**: `screenshots/` directory
- **Naming**: `bulletproof-auth_{test-name}_{step}_{timestamp}.png`
- **Coverage**: Login forms, dashboards, error states, role-specific pages

## Performance Monitoring

The test suite includes built-in performance monitoring:

```typescript
const PERFORMANCE_THRESHOLDS = {
  LOGIN_MAX_TIME: 3000,     // 3 seconds max for login
  LOGOUT_MAX_TIME: 1000,    // 1 second max for logout
  ROUTE_NAVIGATION_MAX_TIME: 2000, // 2 seconds max for route changes
  SESSION_RESTORE_MAX_TIME: 1000,  // 1 second max for session restoration
};
```

Performance results are logged to console during test execution.

## Debugging Failed Tests

### Common Issues and Solutions

1. **Timeouts**:
   - Check if development server is running (`npm run dev`)
   - Verify server is accessible at `http://localhost:5173`
   - Check for JavaScript errors in browser console

2. **Element Not Found**:
   - Review screenshot in `screenshots/` folder
   - Check if UI selectors match current implementation
   - Verify test data (emails, passwords) match mock users

3. **Performance Failures**:
   - Check system performance during test execution
   - Verify no background processes interfering
   - Adjust thresholds if mock API delays change

4. **Authentication Issues**:
   - Clear browser storage before tests
   - Verify mock authentication system is configured
   - Check localStorage/sessionStorage in debug test

### Debug Utilities

The test suite includes debug utilities:

```bash
# Run debug test to log auth system state
npx playwright test tests/auth-bulletproof.spec.ts --grep "debug"
```

## Coverage Report

The bulletproof auth tests provide comprehensive coverage:

- ✅ **Authentication Flows**: Login, logout, session management
- ✅ **Authorization**: Role-based access control for all routes
- ✅ **Performance**: All operations under strict timing thresholds  
- ✅ **Security**: Bypass prevention, malicious input handling
- ✅ **Error Handling**: Network errors, invalid inputs, edge cases
- ✅ **User Experience**: Form validation, loading states, redirects
- ✅ **Cross-browser**: Chromium, Firefox, WebKit support
- ✅ **Mobile**: Responsive design on mobile devices

## Integration with CI/CD

The tests are designed for continuous integration:

- **Headless Execution**: Runs without browser UI in CI
- **Parallel Execution**: Tests can run concurrently for speed
- **Retry Logic**: Built-in retry for flaky network conditions
- **Artifact Collection**: Screenshots and videos on failures
- **Performance Tracking**: Performance metrics for trend analysis

## Maintenance

### Updating Tests

When modifying the authentication system:

1. Update test selectors if UI elements change
2. Modify performance thresholds if API behavior changes
3. Add new test accounts if roles are added
4. Update protected routes list if permissions change
5. Regenerate screenshots for visual comparison

### Test Data Management

- Mock users are defined in `/src/types/auth.ts`
- Route permissions are configured in router files
- Test accounts should mirror production user types
- Performance thresholds should reflect user expectations

## Conclusion

The bulletproof authentication test suite provides comprehensive validation that the authentication system:

- Functions correctly without infinite loops or timeouts
- Enforces proper security and access controls
- Performs well under various conditions  
- Handles errors gracefully
- Maintains data integrity
- Provides excellent user experience

Run these tests regularly to ensure authentication remains rock-solid as the application evolves.