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

// 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

# Navigate to tests directory
cd tests/

# Install dependencies
npm install

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

📋 Execution Commands

Recommended: Comprehensive Test Runner

# 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

# 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

# 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

# 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

# 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

'should validate master dashboard analytics and metrics'

• Dashboard statistics verification
• Performance metrics validation
• Navigation menu functionality
• Section visibility testing

2. Events Management Tests

'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

'should test comprehensive trainer management functionality'

• Trainer approval workflow
• Status management operations
• Performance monitoring
• Bulk trainer actions

4. System Administration Tests

'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

'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

'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:

{
  "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

./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

# 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

# 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

# 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

# Increase timeout
PLAYWRIGHT_TIMEOUT=60000 npm run test:master-trainer

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

Screenshot/Video Issues

# Verify output directories
ls -la test-results/

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

# Check disk space
df -h

Debug Mode

# 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

# .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
• WordPress Testing Best Practices
• Playwright Documentation
• MCP Playwright Tools

🤝 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.