upskill-event-manager/wordpress-dev/tests/e2e/README.md

# HVAC Community Events - E2E Tests

## Trainer Journey Testing

This directory contains end-to-end tests for the complete Trainer User Journey as defined in the project requirements.

### Quick Start

1. Verify your setup:
   ```bash
   cd tests/e2e
   ./verify-setup.sh
   ```

2. Run the trainer journey tests:
   ```bash
   cd ../..  # Go to wordpress-dev directory
   ./bin/run-tests.sh --trainer-journey
   ```

3. Run certificate tests:
   ```bash
   # Using NPM scripts
   npm run test:basic        # Run basic certificate tests
   npm run test:journey      # Run full trainer journey with certificates
   npm run test:cert         # Run certificate tests
   npm run test:cert:gen     # Run certificate generation tests
   
   # Using advanced test runner
   ./bin/run-advanced-tests.sh                        # Basic certificate tests
   ./bin/run-advanced-tests.sh --test journey         # Trainer journey
   ./bin/run-advanced-tests.sh --test journey --debug # With debug mode
   ./bin/run-advanced-tests.sh --test all             # All certificate tests
   ```

4. For detailed testing information:
   ```bash
   # Read the harmonized testing documentation
   cat tests/e2e/docs/harmonized-testing.md
   ```

### Test Coverage

The test suite covers the following trainer journey steps:

- ✅ **Login & Authentication** (Steps 1-2)
- ✅ **Dashboard Access** (Step 3)
- ✅ **Event Management** (Step 4)
  - Create events (Step 4a)
  - View event list (Step 4b)
  - Modify events (Step 4c)
  - Delete events (Step 4d)
- ✅ **Event Details View** (Step 5)
- ⏳ **Event Statistics** (Step 6 - In Progress)
- ⏳ **Order & Attendee Details** (Steps 7-8 - Pending)
- ⏳ **Email Communication** (Step 9 - Phase 2)
- ⏳ **Attendee Check-in** (Step 10)
- ✅ **Certificate Generation** (Step 11 - Now Implemented!)
  - Generate certificates for attendees
  - View and manage certificates
  - Email and revoke certificates

### Project Structure

```
tests/e2e/
├── pages/              # Page Object Model classes
│   ├── BasePage.ts
│   ├── LoginPage.ts
│   ├── DashboardPage.ts
│   ├── CreateEventPage.ts
│   ├── EventSummaryPage.ts
│   ├── ModifyEventPage.ts
│   └── CertificatePage.ts
├── utils/              # Utility classes
│   ├── Config.ts         # Centralized configuration
│   └── CertificateTestData.ts # Certificate test data
├── data/               # Test data
│   ├── test-users.ts
│   └── test-events.ts
├── docs/               # Documentation
│   ├── trainer-journey-testing.md
│   └── harmonized-testing.md  # NEW! Harmonized testing approach
├── test-plan/          # Test planning documents
│   └── trainer-journey-verification.md
├── trainer-journey.test.ts  # Original trainer journey
├── trainer-journey-harmonized.test.ts  # NEW! Harmonized trainer journey
├── certificate-basic.spec.ts  # NEW! Basic certificate tests (compatible with all Playwright versions)
├── certificate-generation-checked-in.test.ts  # Certificate generation tests
├── certificates.test.ts  # Certificate functionality tests
├── CERTIFICATE_TESTING_GUIDE.md  # Certificate testing documentation
├── verify-setup.sh     # Setup verification script
└── README.md          # This file
```

### Advanced Test Infrastructure

```
bin/
├── run-tests.sh              # Original test runner 
├── run-playwright-tests.sh   # Basic Playwright test runner
├── run-advanced-tests.sh     # NEW! Advanced test runner with configuration options
├── setup-staging-test-users.sh  # Setup test users
└── certificate-test.js       # Standalone certificate test script
```

### Running Specific Tests

#### Original Test Runner
```bash
# Run all E2E tests
./bin/run-tests.sh --e2e

# Run only trainer journey tests
./bin/run-tests.sh --trainer-journey

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

# Run certificate tests (legacy method)
./bin/run-certificate-tests.sh generation
./bin/run-certificate-tests.sh reports
```

#### Harmonized Test Runner (Recommended)
```bash
# Run specific test files
npm run test:journey     # Full trainer journey with certificates
npm run test:basic       # Basic certificate tests
npm run test:cert        # Certificate tests
npm run test:cert:gen    # Certificate generation tests

# Run with debug mode
npm run test:journey:debug

# Run with UI mode
npm run test:journey:ui

# Run tests with advanced configuration
./bin/run-advanced-tests.sh --test journey --headed  # With UI visible
./bin/run-advanced-tests.sh --test all --debug      # All certificate tests with debug
```

### Test Results

- Console output shows real-time test progress
- Screenshots saved in `test-results/screenshots/`
- Test reports generated in `test-results/`

### Latest Test Summary (2025-05-21)

The trainer journey and certificate tests are now **✅ PASSING** with the following coverage:

1. **Login and Dashboard Access**: Successfully tests trainer login and dashboard navigation
2. **Event Management**: Complete coverage of event CRUD operations:
   - Create new events with all required fields
   - View events in My Events page (both upcoming and past)
   - Modify existing events
   - Delete events with confirmation
3. **Event Details**: Views individual event pages
4. **Certificate Generation**: Fully implemented!
   - Generate certificates for event attendees
   - Manage certificates (view, email, revoke)
   - Filter and paginate certificate lists
   - Filter by attendee name and email

Key improvements:
- **Harmonized Testing Approach**: Consistent test structure that works with the latest Playwright version
- **Advanced Test Runner**: Simplified execution with multiple configuration options
- **Improved Page Objects**: Enhanced page object models with better encapsulation and reusability
- **Consistent Dependencies**: Fixed Playwright version conflicts in package.json
- **Comprehensive Documentation**: Added detailed testing documentation

Key findings:
- Events created during testing appear in My Events but not in main dashboard (application issue)
- TinyMCE editor requires special handling in tests
- Multiple fallback strategies implemented for form fields
- Certificate generation properly handles checked-in vs. non-checked-in attendees

For complete details on certificate testing, see the [Certificate Testing Guide](CERTIFICATE_TESTING_GUIDE.md) and [Harmonized Testing Approach](./docs/harmonized-testing.md).

### Prerequisites

1. **Environment Setup**
   - `.env` file with staging server credentials
   - Node.js and npm installed
   - Playwright dependencies installed

2. **Staging Server Requirements**
   - Test user `test_trainer` exists
   - Required plugins activated
   - HVAC Community Events plugin deployed

### Troubleshooting

If tests fail, check:

1. **Network Issues**
   - Staging server is accessible
   - No proxy/firewall blocking

2. **Authentication Issues**
   - Test user credentials are correct
   - User has proper role assigned

3. **Element Not Found**
   - Page structure may have changed
   - Update selectors in page objects

4. **Certificate Generation Issues**
   - Verify events have attendees
   - Check if attendees have proper check-in status
   - Review certificate storage permissions

5. **Playwright Version Conflicts**
   - Check package.json to ensure Playwright is in devDependencies
   - Verify you're using version ^1.52.0
   - Run `npm ci` to ensure clean installation
   - Use the `certificate-basic.spec.ts` file which avoids test.describe()

6. **Advanced Test Runner Issues**
   - Ensure the script is executable: `chmod +x bin/run-advanced-tests.sh`
   - Verify your .env file has the correct credentials
   - Try running with the `--headed` flag to see browser interactions

### Contributing

When adding new tests:

1. Use the Page Object Model pattern
2. Add test data to centralized files
3. Update documentation
4. Follow existing naming conventions
5. Use the Config utility for environment variables

### Support

For issues or questions:
- Check the troubleshooting guide above
- Review test output and screenshots
- Check staging server logs
- Contact the development team