# Trainer Journey Testing Documentation

## Overview

This document describes the comprehensive test suite for verifying the complete Trainer User Journey as specified in the HVAC Community Events requirements.

## Test Coverage

The trainer journey test suite covers the following user journey steps:

### Implemented Tests ✅

1. **Trainer Login (Steps 1-2)**
   - Navigate to community login page
   - Login with valid credentials
   - Verify redirect to dashboard
   - Test invalid credentials error handling

2. **Dashboard Access (Step 3)**
   - Access trainer dashboard
   - Verify statistics display (row layout for better visual presentation)
   - Verify events table visibility
   - Test dynamic event filtering without page reload
   - Check navigation elements

3. **Event Management (Step 4)**
   - **Step 4a**: Create new events with all required fields
   - **Step 4b**: View event list in My Events page
   - **Step 4c**: Modify existing events successfully
   - **Step 4d**: Delete events with confirmation

4. **Event Details (Step 5)**
   - View individual event pages
   - Check event information display

### In Progress ⏳

5. **Event Statistics (Step 6)**
   - View event summary page
   - Check event details display
   - View transaction table
   - Access order information

6. **Attendee Details (Steps 7-8)**
   - View attendee information
   - Navigate to order summary
   - Check transaction details

### Recently Implemented ✅

7. **Certificate Management (Steps 11-12)**
   - Generate certificates for events
   - Filter certificates by event and attendee
   - View and download certificates
   - Advanced certificate management

### Partially Implemented ⏳

- Email Communication (Phase 2 - Step 9)
- Attendee Check-in (Step 10)

## Test Structure

### Page Object Model

The test suite uses a Page Object Model (POM) for maintainability:

- `BasePage.ts` - Common page functionality
- `LoginPage.ts` - Login page interactions
- `DashboardPage.ts` - Dashboard operations
- `CreateEventPage.ts` - Event creation form
- `EventSummaryPage.ts` - Event details viewing
- `ModifyEventPage.ts` - Event modification
- `CertificatePage.ts` - Certificate generation and management

### Test Data Management

Test data is centralized in:

- `test-users.ts` - Test user personas
- `test-events.ts` - Event templates
- `CertificateTestData.ts` - Certificate test data generation

## Running the Tests

### Command Line Options

```bash
# Run entire trainer journey test suite
./bin/run-tests.sh --trainer-journey

# Run trainer journey with certificates
npx playwright test tests/e2e/trainer-journey-with-certificates.test.ts

# Run individual test scenarios
./bin/run-tests.sh --e2e --grep @login
./bin/run-tests.sh --e2e --grep @dashboard
./bin/run-tests.sh --e2e --grep @create-event
./bin/run-tests.sh --e2e --grep @certificate

# Run certificate functionality tests only
node bin/certificate-test.js
```

### Environment Requirements

- Staging server must be accessible
- Test trainer user must exist (`test_trainer`)
- Required plugins must be activated
- Environment variables must be set in `.env`

## Test Results

### Success Criteria

All tests pass when:
- Each journey step completes successfully
- Page navigation works correctly
- Data is displayed accurately
- Error scenarios are handled properly

### Output

- Console output shows test progress
- Screenshots saved in `test-results/screenshots/`
- Test report generated in `test-results/`

## Error Handling

The test suite includes error scenario testing:

- Invalid login credentials
- Unauthorized access attempts
- Missing data handling
- Network timeout handling

## Maintenance

### Adding New Tests

1. Create page object if needed
2. Add test data to centralized files
3. Write test scenario in `trainer-journey.test.ts`
4. Update documentation

### Updating Selectors

1. Update page object selectors
2. Test changes locally
3. Verify on staging environment
4. Commit changes with descriptive message

## Troubleshooting

### Common Issues

1. **Login Failures**
   - Verify test user exists
   - Check password is correct
   - Ensure user has trainer role

2. **Navigation Errors**
   - Verify page URLs are correct
   - Check staging server is accessible
   - Ensure plugins are activated

3. **Element Not Found**
   - Update selectors in page objects
   - Check for page structure changes
   - Verify elements load properly

### Debug Mode

Run tests with verbose output:
```bash
./bin/run-tests.sh --trainer-journey --debug
```

## Implementation Summary (2025-05-21)

### Key Achievements
- Successfully implemented Steps 1-7 of trainer journey including certificates
- All tests passing with robust error handling
- Page Object Model architecture for maintainability
- Comprehensive documentation and test data management
- Certificate generation and management testing

### Technical Challenges Resolved
1. **TinyMCE Editor**: Implemented iframe/textarea fallback strategy
2. **Event Persistence**: Adapted tests to verify in My Events page
3. **Form Handling**: Robust field interaction with proper waits
4. **Navigation**: Updated URLs to match actual application paths
5. **Dashboard UI**: Improved responsive layout and dynamic filtering
6. **AJAX Filtering**: Implemented filter functionality without page reload
7. **Certificate Generation**: Successfully tested certificate creation for attendees
8. **Certificate Filtering**: Implemented comprehensive filter testing
9. **Playwright Configuration**: Addressed version conflicts and configuration issues

### Test Artifacts
- Main test files: 
  - `trainer-journey-final.test.ts` - Original trainer journey
  - `trainer-journey-with-certificates.test.ts` - Enhanced journey with certificates
  - `bin/certificate-test.js` - Standalone certificate testing script
- Screenshots: Login, dashboard, event creation, certificates, etc.
- Test reports: Available in `test-results/` directory

## Future Enhancements

1. Complete remaining journey steps (8-10)
2. Enhance email communication testing (Phase 2 features)
3. Add accessibility testing
4. Implement performance metrics
5. Add cross-browser testing
6. Create visual regression tests
7. Add API-level validation
8. Implement continuous integration
9. Improve certificate testing reliability
10. Add certificate PDF content validation