upskill-event-manager/wordpress-dev/TROUBLESHOOTING.md

# Troubleshooting Guide for HVAC Community Events

This document provides solutions for common issues encountered during testing and deployment of the HVAC Community Events plugin.

## Common Test Failures

### Login Issues

#### Symptoms:
- Tests fail with "could not find element"
- Login form selectors not found
- Unexpected redirects during login

#### Solutions:

1. **Verify selectors:**
   ```bash
   # Run login page debug script
   npx playwright test tests/e2e/debug-login-page.spec.ts
   ```

2. **Check login form structure:**
   - Inspect the login form HTML from screenshots
   - Verify form IDs and input names match selectors
   - Update `LoginPage.ts` selectors if necessary

3. **Test user credentials:**
   ```bash
   # Recreate test users
   ./bin/create-test-users.sh
   ```

4. **Clear browser session:**
   ```bash
   # Start with fresh context in tests
   await context.clearCookies();
   ```

### Certificate Generation Issues

#### Symptoms:
- Certificate generation fails
- Empty certificate data
- Missing attendees in certificate list

#### Solutions:

1. **Verify test data:**
   ```bash
   # Create fresh test data
   ./bin/create-test-data-with-checkins.sh
   ```

2. **Check plugin activation:**
   ```bash
   # Verify plugin is active
   ./bin/verify-plugin-status.sh
   ```

3. **Debug certificate system:**
   ```bash
   # Run certificate debug script
   ./bin/debug-certificate-system.sh
   ```

4. **Check for WordPress updates:**
   - Plugin may need updates for compatibility
   - Verify WordPress core version

### Dashboard Issues

#### Symptoms:
- Dashboard elements not found
- Event counts incorrect
- Statistics not displaying

#### Solutions:

1. **Verify dashboard page structure:**
   ```bash
   # Run dashboard debug script
   npx playwright test tests/e2e/debug-dashboard.test.ts
   ```

2. **Check test events:**
   ```bash
   # Create test events for dashboard
   ./bin/create-test-events-admin.sh
   ```

3. **Clear cache:**
   ```bash
   # Clear WordPress cache
   ./bin/clear-wp-cache.sh
   ```

4. **Check event data:**
   - Verify event metadata is correct
   - Check user has permission to view events

## Deployment Issues

### Plugin Activation Failures

#### Symptoms:
- Plugin fails to activate
- Missing functionality after activation
- PHP errors on activation

#### Solutions:

1. **Check activation hooks:**
   - Verify activation hooks are running
   - Check for PHP errors in logs

2. **Reset plugin state:**
   ```bash
   # Deactivate and reactivate plugin
   ./bin/reset-plugin-state.sh
   ```

3. **Check dependencies:**
   - Verify required plugins are active
   - Check plugin compatibility with WordPress version

4. **Debug mode:**
   ```bash
   # Enable WordPress debug mode
   ./bin/enable-wp-debug.sh
   ```

### Database Issues

#### Symptoms:
- Missing or corrupted data
- Database queries failing
- Unexpected query results

#### Solutions:

1. **Check database tables:**
   ```bash
   # Verify database tables exist
   ./bin/check-db-tables.sh
   ```

2. **Repair database:**
   ```bash
   # Run WordPress database repair
   ./bin/repair-wp-database.sh
   ```

3. **Check data integrity:**
   - Verify data relationships are intact
   - Check for orphaned records

4. **Regenerate test data:**
   ```bash
   # Clean and regenerate test data
   ./bin/regenerate-test-data.sh
   ```

## Performance Issues

### Slow Test Execution

#### Symptoms:
- Tests taking longer than expected
- Timeouts during test execution
- Inconsistent test timing

#### Solutions:

1. **Profile test execution:**
   ```bash
   # Run tests with timing information
   npx playwright test --reporter=list,json
   ```

2. **Optimize selectors:**
   - Use more specific selectors
   - Avoid complex selector chains

3. **Adjust timeouts:**
   ```typescript
   // Increase timeouts for slow operations
   await page.waitForSelector(selector, { timeout: 30000 });
   ```

4. **Reduce test dependencies:**
   - Make tests more independent
   - Reduce shared state between tests

### Browser Performance

#### Symptoms:
- Browser becomes unresponsive
- High CPU/memory usage
- Slow UI interactions

#### Solutions:

1. **Use headless mode:**
   ```bash
   # Run tests in headless mode
   npx playwright test --headless
   ```

2. **Limit concurrent tests:**
   ```bash
   # Run with fewer workers
   npx playwright test --workers=2
   ```

3. **Clear browser cache:**
   ```typescript
   // Clear cache before tests
   await page.context().clearCookies();
   ```

4. **Optimize page load:**
   ```typescript
   // Wait for network idle
   await page.waitForLoadState('networkidle');
   ```

## Environment Issues

### Staging Environment

#### Symptoms:
- Tests pass locally but fail on staging
- Different behavior between environments
- Connectivity issues with staging

#### Solutions:

1. **Verify staging config:**
   ```bash
   # Check staging configuration
   ./bin/verify-staging-config.sh
   ```

2. **Test connectivity:**
   ```bash
   # Check connectivity to staging
   ./bin/check-staging-connectivity.sh
   ```

3. **Sync local with staging:**
   ```bash
   # Sync local environment with staging
   ./bin/sync-staging.sh
   ```

4. **Debug staging environment:**
   ```bash
   # Run diagnostic on staging
   ./bin/diagnose-staging.sh
   ```

### CI/CD Environment

#### Symptoms:
- Tests pass locally but fail in CI
- Timeouts specific to CI environment
- Missing dependencies in CI

#### Solutions:

1. **Check CI configuration:**
   - Verify CI environment variables
   - Check dependency installation

2. **Increase CI timeouts:**
   ```yaml
   # In CI config
   timeout-minutes: 30
   ```

3. **Debug CI environment:**
   ```bash
   # Add debugging output to CI
   set -x
   env | sort
   ```

4. **Use CI-specific configs:**
   ```typescript
   // In playwright.config.ts
   const config = {
     // CI-specific settings
     retries: process.env.CI ? 2 : 0,
     timeout: process.env.CI ? 60000 : 30000,
   };
   ```

## Advanced Troubleshooting

### Analyzing Test Videos

Playwright records videos of test runs. Use them to identify visual issues:

```bash
# Run tests with video recording
npx playwright test --video=on

# Videos are saved in test-results directory
```

### Using Trace Viewer

For detailed analysis of test execution:

```bash
# Run tests with tracing
npx playwright test --trace=on

# Open trace viewer
npx playwright show-trace test-results/trace.zip
```

### Manual Test Recovery

If automated tests consistently fail:

1. Create a simpler test case that isolates the issue
2. Run in headed mode with slower execution:
   ```bash
   npx playwright test --headed --timeout=60000 --debug
   ```
3. Step through the test manually to identify the exact failure point
4. Update selectors or test logic based on findings

### Health Check Script

Run a comprehensive health check:

```bash
# Full system health check
./bin/health-check.sh

# Output detailed diagnostics
./bin/health-check.sh --verbose
```

## Getting Help

If issues persist after trying these solutions:

1. Check the issue tracker for similar problems
2. Consult the WordPress support forums
3. Review The Events Calendar plugin documentation
4. Contact the development team with detailed reproduction steps