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:

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

   # Recreate test users
   ./bin/create-test-users.sh
   

4. Clear browser session:

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

   # Create fresh test data
   ./bin/create-test-data-with-checkins.sh
   

2. Check plugin activation:

   # Verify plugin is active
   ./bin/verify-plugin-status.sh
   

3. Debug certificate system:

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

   # Run dashboard debug script
   npx playwright test tests/e2e/debug-dashboard.test.ts
   

2. Check test events:

   # Create test events for dashboard
   ./bin/create-test-events-admin.sh
   

3. Clear cache:

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

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

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

   # Verify database tables exist
   ./bin/check-db-tables.sh
   

2. Repair database:

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

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

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

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

   # Run tests in headless mode
   npx playwright test --headless
   

2. Limit concurrent tests:

   # Run with fewer workers
   npx playwright test --workers=2
   

3. Clear browser cache:

   // Clear cache before tests
   await page.context().clearCookies();
   

4. Optimize page load:

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

   # Check staging configuration
   ./bin/verify-staging-config.sh
   

2. Test connectivity:

   # Check connectivity to staging
   ./bin/check-staging-connectivity.sh
   

3. Sync local with staging:

   # Sync local environment with staging
   ./bin/sync-staging.sh
   

4. Debug staging environment:

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

   # In CI config
   timeout-minutes: 30
   

3. Debug CI environment:

   # Add debugging output to CI
   set -x
   env | sort
   

4. Use CI-specific configs:

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

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

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

   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:

# 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