upskill-event-manager/tests/README-MASTER-TRAINER-COMPREHENSIVE.md

# Master Trainer Comprehensive E2E Test Suite

**Agent C Implementation - Complete Coverage of 12 Master Trainer Administrative Pages**

This comprehensive test suite provides thorough end-to-end testing of all Master Trainer functionality using the HVAC Testing Framework 2.0 with MCP Playwright integration.

## Overview

### 📊 Test Coverage

**12 Master Trainer Administrative Pages:**
1. ✅ `master-trainer/master-dashboard/` - Analytics & overview
2. ✅ `master-trainer/events/` - System-wide event management
3. ✅ `master-trainer/trainers/` - Trainer oversight & management
4. ✅ `master-trainer/announcements/` - System announcements
5. ✅ `master-trainer/pending-approvals/` - Approval workflow management
6. ✅ `master-trainer/communication-templates/` - Template management
7. ✅ `master-trainer/google-sheets/` - Spreadsheet integration
8. ✅ `master-trainer/import-export/` - Data import/export workflows
9. ✅ Layout consistency validation across all pages

### 🎯 Key Test Scenarios

#### **Master Dashboard Analytics Validation**
- Revenue calculations and reporting accuracy
- Trainer performance metrics aggregation
- Event statistics and trend analysis
- Real-time data updates and caching
- Navigation menu functionality

#### **Trainer Management Operations**
- Trainer approval and status management
- Performance monitoring and reporting
- Trainer communication and feedback systems
- Bulk trainer operations and updates
- Trainer profile management

#### **System Administration Features**
- Announcement creation and distribution
- Communication template management
- Data import/export functionality
- System configuration and settings
- Google Sheets integration

#### **Layout Standardization**
- Single-column design consistency
- Navigation and breadcrumb validation
- Master trainer-specific styling and branding
- Mobile responsiveness for administrative functions
- Cross-browser compatibility

#### **Security & Error Validation**
- WordPress error detection on all pages
- Authentication and authorization verification
- Role-based access control testing
- Security header and nonce validation

## 🚀 Quick Start

### Prerequisites

- Node.js 16+
- WordPress with HVAC plugin installed
- Access to staging environment: `https://upskill-staging.measurequick.com`
- Master trainer test accounts configured

### Test Accounts

```javascript
// Primary account
Username: test_master
Password: TestMaster123!
Role: hvac_master_trainer

// Alternative account
Username: JoeMedosch@gmail.com
Password: JoeTrainer2025@
Role: hvac_master_trainer
```

### Installation & Setup

```bash
# Navigate to tests directory
cd tests/

# Install dependencies
npm install

# Initialize framework (if needed)
npm run framework:init
```

## 📋 Execution Commands

### **Recommended: Comprehensive Test Runner**
```bash
# Full comprehensive test suite with reporting
npm run test:master-trainer-comprehensive

# With GNOME session support (headed testing)
DISPLAY=:0 XAUTHORITY=/run/user/1000/.mutter-Xwaylandauth.U8VEB3 npm run test:master-trainer-comprehensive

# Headless execution
HEADLESS=true npm run test:master-trainer-comprehensive
```

### **Direct Playwright Execution**
```bash
# Standard execution
npm run test:master-trainer

# Headed execution with GNOME support
npm run test:master-trainer-headed

# Debug mode with pause points
npm run test:master-trainer-debug

# Custom configuration
BASE_URL=https://upskill-staging.measurequick.com npm run test:master-trainer
```

### **Manual Playwright Command**
```bash
# Full control
npx playwright test e2e/master-trainer-comprehensive.test.js \
  --config=playwright-master-trainer.config.js \
  --headed \
  --project=chromium-headed \
  --timeout=300000
```

## 🎨 GNOME Session Support

The test suite includes comprehensive support for headed testing in GNOME desktop environments:

### **Environment Detection**
```bash
# Desktop environment check
XDG_CURRENT_DESKTOP=GNOME    # Detected automatically
DISPLAY=:0                   # X11 display
WAYLAND_DISPLAY=wayland-0    # Wayland display
```

### **Headed Testing Features**
- Visual debugging with slow motion
- Real-time test execution observation
- Interactive debugging with pause points
- Full HD viewport (1920x1080)
- Screenshot capture at each major step
- Video recording of full test execution

### **Xwayland Integration**
```bash
# Set Xwayland authority for GNOME
export XAUTHORITY=/run/user/1000/.mutter-Xwaylandauth.U8VEB3

# Enable headed testing
export PLAYWRIGHT_HEADED=true
export HEADLESS=false
```

## 📁 File Structure

```
tests/
├── e2e/
│   └── master-trainer-comprehensive.test.js    # Main test suite
├── page-objects/
│   └── master-trainer/
│       ├── MasterTrainerDashboard.js           # Dashboard interactions
│       ├── MasterTrainerEvents.js              # Events management
│       └── MasterTrainerTrainers.js            # Trainers management
├── scripts/
│   └── run-master-trainer-comprehensive.js     # Test runner
├── playwright-master-trainer.config.js         # Playwright config
├── test-results/
│   ├── master-trainer-comprehensive/           # Test artifacts
│   ├── screenshots/master-trainer/             # Screenshots
│   └── videos/master-trainer/                  # Video recordings
└── README-MASTER-TRAINER-COMPREHENSIVE.md      # This documentation
```

## 🧪 Test Categories

### **1. Analytics Validation Tests**
```javascript
'should validate master dashboard analytics and metrics'
```
- Dashboard statistics verification
- Performance metrics validation
- Navigation menu functionality
- Section visibility testing

### **2. Events Management Tests**
```javascript
'should test comprehensive events management functionality'
```
- Events list and table interaction
- Search and filtering capabilities
- Bulk operations testing
- System-wide event oversight

### **3. Trainer Management Tests**
```javascript
'should test comprehensive trainer management functionality'
```
- Trainer approval workflow
- Status management operations
- Performance monitoring
- Bulk trainer actions

### **4. System Administration Tests**
```javascript
'should test comprehensive announcements system functionality'
'should test communication templates management functionality'
'should test Google Sheets integration functionality'
```
- Announcement creation and distribution
- Template management workflows
- Data import/export operations
- Google Sheets integration

### **5. Layout Consistency Tests**
```javascript
'should validate layout consistency across all master trainer pages'
'should test mobile responsiveness across master trainer pages'
```
- Cross-page layout validation
- Responsive design testing
- Navigation consistency
- Visual element verification

### **6. Security & Error Detection Tests**
```javascript
'should validate WordPress security and error handling'
```
- WordPress error detection
- Authentication state verification
- Security header validation
- Role-based access control

## 📊 Test Reporting

### **Comprehensive Report Generation**

The test runner automatically generates detailed reports:

```json
{
  "testSuite": "Master Trainer Comprehensive E2E Tests",
  "timestamp": "2025-08-27T10:00:00.000Z",
  "duration": 300000,
  "environment": {
    "baseUrl": "https://upskill-staging.measurequick.com",
    "headless": false,
    "desktop": "GNOME"
  },
  "coverage": {
    "totalPages": 12,
    "testedPages": [...],
    "testCategories": [...]
  },
  "results": {...},
  "screenshots": [...]
}
```

### **Report Locations**
```bash
./test-results/master-trainer-comprehensive/
├── comprehensive-report.json           # Detailed JSON report
├── html-report/                       # Interactive HTML report
├── master-trainer-results.json       # Playwright results
├── junit-results.xml                  # JUnit XML report
└── videos/                           # Test execution videos
```

### **Screenshot Documentation**
All major test steps capture screenshots with descriptive names:
```
master-dashboard-initial.png
events-management-comprehensive.png
trainer-management-comprehensive.png
layout-dashboard.png
security-validation-complete.png
```

## 🔧 Configuration

### **Environment Variables**
```bash
# Base configuration
BASE_URL=https://upskill-staging.measurequick.com
HEADLESS=false
PLAYWRIGHT_HEADED=true

# GNOME session
DISPLAY=:0
WAYLAND_DISPLAY=wayland-0
XDG_CURRENT_DESKTOP=GNOME
XAUTHORITY=/run/user/1000/.mutter-Xwaylandauth.U8VEB3

# Test framework
HVAC_TEST_ENV=staging
TEST_RESULTS_DIR=./test-results/master-trainer-comprehensive
```

### **Playwright Configuration**
- **Timeout**: 5 minutes per test
- **Retries**: 2 (1 in non-CI environments)
- **Workers**: 1 (sequential execution)
- **Screenshots**: On failure + comprehensive capture
- **Videos**: On failure (always in headed mode)
- **Trace**: On failure with full context

## 📈 Performance Metrics

### **Expected Execution Times**
- **Full comprehensive suite**: ~15-20 minutes
- **Individual test**: 2-5 minutes
- **Page navigation**: 5-10 seconds
- **Screenshot capture**: 1-2 seconds

### **Resource Requirements**
- **Memory**: 2-4 GB during execution
- **Disk**: 500 MB for screenshots/videos
- **Network**: Stable connection to staging environment

## 🐛 Troubleshooting

### **Common Issues & Solutions**

#### **GNOME Session Issues**
```bash
# Check desktop environment
echo $XDG_CURRENT_DESKTOP
echo $DISPLAY
echo $WAYLAND_DISPLAY

# Verify X11 access
xset q

# Set proper authority
export XAUTHORITY=/run/user/1000/.mutter-Xwaylandauth.U8VEB3
```

#### **Authentication Failures**
```bash
# Verify test accounts
curl -u test_master:TestMaster123! https://upskill-staging.measurequick.com/wp-json/wp/v2/users/me

# Clear storage states
npm run clean:auth-states

# Force fresh login
FORCE_FRESH_LOGIN=true npm run test:master-trainer
```

#### **Page Load Timeouts**
```bash
# Increase timeout
PLAYWRIGHT_TIMEOUT=60000 npm run test:master-trainer

# Check staging availability
curl -I https://upskill-staging.measurequick.com
```

#### **Screenshot/Video Issues**
```bash
# Verify output directories
ls -la test-results/

# Clear previous results
rm -rf test-results/master-trainer-comprehensive/

# Check disk space
df -h
```

### **Debug Mode**
```bash
# Enable debug logging
DEBUG=hvac:* npm run test:master-trainer-comprehensive

# Run with Playwright inspector
npm run test:master-trainer-debug

# Pause on first line
PWDEBUG=1 npm run test:master-trainer
```

## ✅ Success Criteria

### **Test Completion Requirements**
- [ ] All 12 master trainer pages load without WordPress errors
- [ ] Authentication works with both test accounts
- [ ] Dashboard analytics display correctly
- [ ] Events management functionality accessible
- [ ] Trainer management operations available
- [ ] Announcements system functional
- [ ] Layout consistency across all pages
- [ ] Security validation passes
- [ ] Mobile responsiveness verified
- [ ] Comprehensive screenshots captured

### **Performance Benchmarks**
- [ ] Page load times < 10 seconds
- [ ] Test execution time < 25 minutes
- [ ] No JavaScript console errors
- [ ] All assertions pass successfully
- [ ] Video recordings complete without corruption

## 🚀 Integration with CI/CD

### **Forgejo Actions Integration**
```yaml
# .forgejo/workflows/master-trainer-e2e.yml
name: Master Trainer E2E Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  master-trainer-e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: |
          cd tests
          npm install
                    
      - name: Run Master Trainer E2E Tests
        run: |
          cd tests
          HEADLESS=true npm run test:master-trainer-comprehensive
                    
      - name: Upload test results
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: master-trainer-test-results
          path: tests/test-results/
```

## 📚 Additional Resources

- **[HVAC Testing Framework 2.0 Guide](./README-FRAMEWORK-2.0.md)**
- **[WordPress Testing Best Practices](../docs/WORDPRESS-BEST-PRACTICES.md)**
- **[Playwright Documentation](https://playwright.dev/docs/intro)**
- **[MCP Playwright Tools](https://github.com/anthropics/claude-mcp-server)**

## 🤝 Contributing

### **Adding New Tests**
1. Follow the BaseTest.create() pattern
2. Use descriptive test names and categories
3. Include comprehensive screenshot capture
4. Add proper WordPress error detection
5. Update documentation accordingly

### **Extending Page Objects**
1. Inherit from BasePage
2. Define comprehensive selectors
3. Implement WordPress-aware waiting
4. Add error handling for missing elements
5. Include JSDoc documentation

---

**📋 Test Suite Status: READY FOR EXECUTION**

This comprehensive test suite provides complete coverage of all Master Trainer administrative functionality with professional-grade testing patterns, comprehensive reporting, and full GNOME session support for visual debugging.