blackcanyontickets/reactrebuild0825/tests/README.md

# Black Canyon Tickets - QA Test Suite

Comprehensive Playwright-based end-to-end testing for the React rebuild of Black Canyon Tickets platform.

## Overview

This test suite validates critical user flows and functionality for a premium ticketing platform serving upscale venues like dance performances, weddings, and galas.

## Test Coverage

### 🔴 Critical Test Suites
- **Authentication (`auth.spec.ts`)** - Login/logout flows, protected routes, session management
- **Navigation (`navigation.spec.ts`)** - Sidebar navigation, mobile menu, breadcrumbs, routing

### 🟡 Standard Test Suites  
- **Theme Switching (`theme.spec.ts`)** - Light/dark theme transitions and persistence
- **Responsive Design (`responsive.spec.ts`)** - Mobile, tablet, desktop layouts and touch interactions
- **UI Components (`components.spec.ts`)** - Buttons, forms, cards, modals, interactive elements

## Demo Accounts

The following mock accounts are available for testing:

```typescript
// Admin User
Email: admin@example.com
Password: demo123
Organization: Black Canyon Tickets (Enterprise)

// Organizer User  
Email: organizer@example.com
Password: demo123
Organization: Elite Events Co. (Pro)

// Staff User
Email: staff@example.com
Password: demo123
Organization: Wedding Venues LLC (Free)
```

## Quick Start

### Prerequisites
- Node.js 18+ installed
- Application running on `localhost:5173` (Vite dev server)

### Installation
```bash
npm install
npx playwright install
```

### Running Tests

#### Full QA Suite
```bash
# Run all tests with comprehensive reporting
npm run test:qa

# Run only critical tests (auth + navigation)
npm run test:qa:critical

# Run with visible browser windows
npm run test:qa:headed
```

#### Individual Test Suites
```bash
npm run test:auth         # Authentication flows
npm run test:navigation   # Navigation and routing
npm run test:theme        # Theme switching
npm run test:responsive   # Responsive design
npm run test:components   # UI components
```

#### Playwright Commands
```bash
# Run all tests
npm test

# Run with Playwright UI
npm run test:ui

# Run with visible browser
npm run test:headed

# Run specific test file
npx playwright test tests/auth.spec.ts
```

## Test Reports

After running tests, comprehensive reports are generated:

### HTML Report
- **Location**: `./playwright-report/index.html`
- **Content**: Interactive test results with videos and traces
- **View**: Open in browser for detailed analysis

### QA Report  
- **Location**: `./test-results/qa-report.md`
- **Content**: Executive summary with pass/fail status
- **Format**: Markdown for easy sharing

### Screenshots
- **Location**: `./screenshots/`
- **Naming**: `{test-suite}_{test-name}_{timestamp}.png`
- **Content**: Visual evidence of all test states

## Test Architecture

### Page Object Model
Tests use data-testid attributes for reliable element selection:

```typescript
// Example selectors used in tests
'[data-testid="email-input"]'
'[data-testid="login-button"]'
'[data-testid="user-menu"]'
'[data-testid="nav-dashboard"]'
```

### Screenshot Strategy
Every test captures screenshots at key moments:
- Before/after state changes
- Error conditions
- Success confirmations
- Visual regression validation

### Browser Support
Tests run against multiple browsers:
- Chromium (Desktop + Mobile Chrome)
- Firefox (Desktop)
- WebKit (Desktop + Mobile Safari)

## Test Scenarios

### Authentication Flow
```
1. Visit homepage → redirect to login
2. Enter valid credentials → successful login
3. Navigate protected routes → verify access
4. Logout → redirect to login
5. Enter invalid credentials → show error
6. Test remember me functionality
```

### Navigation Flow
```
1. Login as different user roles
2. Test sidebar navigation
3. Verify mobile menu behavior
4. Check breadcrumb updates
5. Test keyboard navigation
6. Verify active state indicators
```

### Theme Switching Flow
```
1. Start in default light theme
2. Toggle to dark theme → verify visual changes
3. Refresh page → verify persistence
4. Navigate between pages → verify consistency
5. Test system preference detection
```

### Responsive Design Flow
```
1. Test mobile viewport (375px)
2. Test tablet viewport (768px)  
3. Test desktop viewport (1280px)
4. Verify touch interactions
5. Check orientation changes
6. Validate text scaling
```

### Component Testing Flow
```
1. Test button states (default, hover, disabled)
2. Test form validation and error states
3. Test modal open/close functionality
4. Test dropdown menu interactions
5. Test loading and skeleton states
```

## Accessibility Testing

Tests include accessibility validation:
- Keyboard navigation through all interactive elements
- Tab order verification
- Focus management
- Skip-to-content functionality
- ARIA attribute validation

## Performance Considerations

- Tests use proper wait strategies (avoid hard sleeps)
- Network throttling for realistic conditions
- Timeout configurations for different operations
- Parallel execution where safe

## Troubleshooting

### Common Issues

**Tests failing due to missing application**
```bash
# Ensure dev server is running
npm run dev
# Then run tests in separate terminal
npm run test:qa
```

**Browser installation issues**
```bash
# Reinstall browsers
npx playwright install --force
```

**Screenshot permissions**
```bash
# Ensure screenshots directory exists and is writable
mkdir -p screenshots
chmod 755 screenshots
```

### Debug Mode
```bash
# Run specific test with debug mode
npx playwright test tests/auth.spec.ts --debug

# Run with trace viewer
npx playwright test --trace on
```

## CI/CD Integration

For continuous integration environments:

```bash
# CI-optimized test run
CI=true npm run test:qa:critical

# Generate JUnit reports
npx playwright test --reporter=junit
```

## Contributing

When adding new tests:

1. Follow the existing naming convention
2. Use data-testid attributes for selectors
3. Include comprehensive screenshots
4. Add both success and error scenarios
5. Update this README with new test coverage

### Test File Structure
```typescript
// Standard test file template
import { test, expect, Page } from '@playwright/test';
import path from 'path';

async function takeScreenshot(page: Page, name: string) {
  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
  const fileName = `testsuite_${name}_${timestamp}.png`;
  await page.screenshot({ 
    path: path.join('screenshots', fileName),
    fullPage: true
  });
}

test.describe('Test Suite Name', () => {
  test.beforeEach(async ({ page }) => {
    // Setup code
  });

  test('should test specific functionality', async ({ page }) => {
    // Test implementation
    await takeScreenshot(page, 'test-description');
  });
});
```

## Contact

For questions about the QA test suite:
- Review test failures in `./playwright-report/index.html`
- Check screenshots in `./screenshots/` directory
- Consult QA report in `./test-results/qa-report.md`