blackcanyontickets/TICKET_TESTING_GUIDE.md

# Ticket Purchasing Test Suite - Black Canyon Tickets

## Overview

This comprehensive test suite validates the complete ticket purchasing workflow for the Black Canyon Tickets platform. The tests ensure customers can successfully purchase tickets without issues across different devices, scenarios, and edge cases.

## Test Files Created

### 1. `test-ticket-purchasing-comprehensive.cjs`
**Purpose**: Complete test suite with mocked data and responses  
**Features**:
- End-to-end ticket purchasing flow validation
- Multiple ticket types and quantity testing
- Mobile responsive design verification
- Form validation and error handling
- Presale code functionality testing
- Inventory management and reservation testing
- Accessibility compliance validation
- Visual regression testing with screenshots
- Performance and load testing

### 2. `test-ticket-purchasing-integration.cjs`
**Purpose**: Real application integration tests  
**Features**:
- Tests against actual BCT application running on localhost:4321
- Real API endpoint validation
- Actual React component interaction testing
- Network request/response monitoring
- Error state handling verification
- Mobile viewport testing
- Accessibility standards checking

### 3. `test-data-setup.cjs`
**Purpose**: Test data management and mock event creation  
**Features**:
- Creates mock events with different scenarios
- Validates presale code functionality
- Tests sold-out and low-stock scenarios
- Provides reusable test data patterns

### 4. `run-ticket-tests.sh`
**Purpose**: Test execution helper script  
**Features**:
- Automated test runner with multiple modes
- Server status checking
- Test report generation
- Screenshot management

## Test Coverage Areas

### ✅ Basic Ticket Purchasing Flow
- Event page loading and display
- Ticket type selection and quantity changes
- Price calculation with platform fees
- Customer information form completion
- Purchase submission and confirmation

### ✅ Multiple Ticket Types and Quantities
- Different ticket types (General, VIP, Student, etc.)
- Quantity limits and availability checking
- Mixed ticket type selection
- Pricing calculations for multiple items

### ✅ Mobile Responsive Design
- Mobile viewport (375x667) testing
- Tablet viewport (768x1024) testing
- Touch interaction validation
- Mobile form usability

### ✅ Form Validation and Error Handling
- Email format validation
- Required field enforcement
- Sold-out ticket handling
- Network error graceful degradation
- Invalid input rejection

### ✅ Presale Code Functionality
- Presale code input display
- Code validation (valid/invalid)
- Access control for restricted tickets
- Error message display

### ✅ Inventory Management
- Ticket reservation creation
- Reservation timer display and countdown
- Automatic reservation expiry
- Reservation failure handling
- API request/response validation

### ✅ Accessibility Testing
- Keyboard navigation support
- ARIA labels and roles validation
- Screen reader compatibility
- Color contrast verification
- Focus management

### ✅ Visual Regression Testing
- Baseline screenshot capture
- Different state comparisons
- Error state visual validation
- Mobile layout verification
- Theme consistency checking

## Running the Tests

### Prerequisites
```bash
# Ensure development server is running
npm run dev

# Install Playwright if not already installed
npm install -D @playwright/test
npx playwright install
```

### Test Execution Commands

#### Quick Start
```bash
# Make test runner executable (if needed)
chmod +x run-ticket-tests.sh

# Run all tests
./run-ticket-tests.sh

# Or run integration tests directly
npx playwright test test-ticket-purchasing-integration.cjs
```

#### Specific Test Modes
```bash
# Integration tests (real app)
./run-ticket-tests.sh integration

# Comprehensive tests (with mocks)
./run-ticket-tests.sh comprehensive

# Test data setup validation
./run-ticket-tests.sh data-setup

# Interactive UI mode
./run-ticket-tests.sh ui

# Debug mode (step through tests)
./run-ticket-tests.sh debug

# Mobile-specific tests only
./run-ticket-tests.sh mobile

# Accessibility tests only
./run-ticket-tests.sh accessibility
```

#### Direct Playwright Commands
```bash
# Run with HTML reporter
npx playwright test test-ticket-purchasing-integration.cjs --reporter=html

# Run with UI interface
npx playwright test test-ticket-purchasing-integration.cjs --ui

# Run specific test
npx playwright test test-ticket-purchasing-integration.cjs --grep "mobile"

# Run with headed browser (visible)
npx playwright test test-ticket-purchasing-integration.cjs --headed

# Debug mode
npx playwright test test-ticket-purchasing-integration.cjs --debug
```

## Screenshots and Reports

### Screenshot Locations
```
screenshots/
├── event-page-initial.png
├── ticket-selection-2-tickets.png
├── pre-purchase-form-filled.png
├── mobile-event-page.png
├── sold-out-state.png
├── color-contrast-verification.png
└── visual-regression-*.png
```

### Test Reports
```bash
# View HTML report
npx playwright show-report

# Report location
./playwright-report/index.html
```

## Test Architecture

### Page Object Pattern
The tests use the Page Object Model for maintainable and reusable test code:

```javascript
class TicketPurchasePage {
  constructor(page) {
    this.page = page;
    this.ticketTypes = page.locator('.ticket-type');
    this.orderSummary = page.locator('[data-test="order-summary"]');
    // ... other locators
  }
  
  async selectTicketQuantity(index, quantity) {
    // Implementation
  }
}
```

### Test Data Management
Structured test data with different scenarios:

```javascript
const testEvents = {
  basicEvent: { /* normal event */ },
  presaleEvent: { /* requires presale code */ },
  soldOutEvent: { /* no tickets available */ },
  lowStockEvent: { /* limited availability */ }
};
```

### Mock API Responses
Controlled testing environment with predictable responses:

```javascript
await page.route('**/api/inventory/availability/*', async route => {
  await route.fulfill({
    status: 200,
    body: JSON.stringify({ success: true, availability: {...} })
  });
});
```

## Key Test Scenarios

### 1. Happy Path Purchase Flow
- User navigates to event page
- Selects ticket type and quantity
- Fills customer information
- Completes purchase successfully

### 2. Edge Cases
- Sold out tickets
- Network failures
- Invalid form data
- Expired reservations
- Presale code requirements

### 3. Mobile Experience
- Touch interactions
- Form usability on small screens
- Navigation and scrolling
- Responsive layout validation

### 4. Error Handling
- API failures
- Validation errors
- Network timeouts
- Invalid user inputs

## Continuous Integration

### GitHub Actions Integration
```yaml
name: Ticket Purchase Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install
      - run: npx playwright install
      - run: npm run dev &
      - run: npx playwright test test-ticket-purchasing-integration.cjs
```

### Local Development Workflow
1. Start development server: `npm run dev`
2. Run tests: `./run-ticket-tests.sh`
3. Review screenshots: Check `screenshots/` directory
4. Fix issues: Update code and re-run tests
5. Commit: Include test updates with code changes

## Troubleshooting

### Common Issues

#### Server Not Running
```bash
# Error: ECONNREFUSED
# Solution: Start the development server
npm run dev
```

#### Test Timeouts
```bash
# Increase timeout in test configuration
test.setTimeout(60000);
```

#### Screenshot Differences
```bash
# Update baseline screenshots
npx playwright test --update-snapshots
```

#### Flaky Tests
```bash
# Run with retries
npx playwright test --retries=3
```

### Debugging Tips

1. **Use headed mode** to see browser actions:
   ```bash
   npx playwright test --headed
   ```

2. **Add debug pauses** in test code:
   ```javascript
   await page.pause(); // Pauses execution
   ```

3. **Check network requests**:
   ```javascript
   page.on('request', request => console.log(request.url()));
   ```

4. **Capture additional screenshots**:
   ```javascript
   await page.screenshot({ path: 'debug.png' });
   ```

## Test Metrics and Coverage

### Performance Targets
- Page load time: < 5 seconds
- Interaction response: < 2 seconds
- Form submission: < 3 seconds

### Accessibility Standards
- WCAG 2.1 AA compliance
- Keyboard navigation support
- Screen reader compatibility
- Color contrast ratios

### Browser Support
- Chromium (primary)
- Firefox (optional)
- WebKit/Safari (optional)

## Contributing

### Adding New Tests
1. Follow the existing page object pattern
2. Include both positive and negative test cases
3. Add appropriate screenshots
4. Update this documentation

### Test Naming Convention
```javascript
test('should [action] [expected result]', async ({ page }) => {
  // Test implementation
});
```

### Code Quality
- Use TypeScript annotations where possible
- Include descriptive console.log statements
- Handle async operations properly
- Clean up resources after tests

## Future Enhancements

### Planned Improvements
- [ ] Stripe payment integration testing
- [ ] Email receipt validation
- [ ] QR code generation testing
- [ ] Multi-language support testing
- [ ] Performance benchmarking
- [ ] Load testing with multiple users

### Integration Opportunities
- API contract testing
- Database state validation
- Cross-browser testing
- Visual diff automation
- Automated accessibility auditing

---

**Test Suite Version**: 1.0  
**Last Updated**: August 18, 2024  
**Maintainer**: QA Engineering Team  

For questions or issues, please refer to the CLAUDE.md file or create an issue in the project repository.