upskill-event-manager/wordpress-dev

WordPress Development & Staging Environments

Status: Active/Authoritative Last Updated: April 23, 2025 Scope: Development and staging environment setup and configuration

This repository contains configuration and tools for the Cloudways staging environment. The staging environment provides a production-like testing platform for development, testing, and deployment validation. Local Docker-based development is no longer supported; all development and testing should be performed using the Cloudways staging server.

Environment Overview

Staging Environment (Cloudways)

• Production-like environment for all development, testing, and deployment validation

• No local server or Docker-based development is supported

• SSH access to Cloudways server is required

• Use sshpass for automated scripts (optional)

• MySQL client for database operations

• All environment variables must be set in .env:

  UPSKILL_STAGING_URL=https://upskill-staging.measurequick.com/
  UPSKILL_STAGING_IP=146.190.76.204
  UPSKILL_STAGING_SSH_USER=roodev
  UPSKILL_STAGING_PASS=<password>
  UPSKILL_STAGING_PATH=/home/974670.cloudwaysapps.com/uberrxmprk/public_html
  UPSKILL_STAGING_DB_NAME=uberrxmprk
  UPSKILL_STAGING_DB_USER=uberrxmprk
  UPSKILL_STAGING_DB_PASSWORD=<password>
  

Staging Environment Setup

1. Configuration

# Deploy configuration to staging
./bin/deploy-config-staging.sh

# Verify staging environment
./bin/verify-staging.sh

2. Testing Setup

# Configure test environment on staging
./bin/configure-staging-tests.sh

# Run unit tests on staging
./bin/run-staging-unit-tests.sh

3. Test User Setup

A test user with the 'hvac_trainer' role is required for running the E2E tests that cover trainer-specific workflows. This user can be created on the staging environment using the ./bin/setup-staging-test-users.sh script.

Execute the script from the wordpress-dev/ directory after the HVAC Community Events plugin has been deployed and activated on the staging server:

./bin/setup-staging-test-users.sh

The script creates a user with the username test_trainer and password from environment variables.

3. Data Synchronization

# Sync data from staging to local backup
./bin/sync-staging.sh

# Deploy local changes to staging
./bin/deploy-plugin.sh

Environment Setup

1. Configuration

The .env file contains:

• Staging server details
• Database credentials
• WordPress authentication
• SSL configuration
• Development settings

Important: Ensure the PHP memory_limit is set sufficiently high (e.g., 512M) in the Cloudways PHP settings via the Cloudways dashboard.

2. Creating New Backups

If you need to create a new backup from production:

# Create a new backup from production
./bin/sync-production-fixed.sh

This will create a new backup in the backups/ directory with the current date and time.

3. Plugin Setup

Required plugins are included in the backups:

• The Events Calendar Suite (6.10.2+)
• Event Tickets Suite (5.19.3+)
• Additional required plugins

4. Automatic Page Creation

Upon activation, the HVAC Community Events plugin automatically creates the following required pages if they don't already exist:

• Community Login (/community-login/)
• Trainer Registration (/trainer-registration/)
• Trainer Dashboard (/hvac-dashboard/)

Ensure the plugin is deactivated and reactivated if these pages are missing after setup.

Access Points

• WordPress Site:
  • URL: https://upskill-staging.measurequick.com/
• WordPress Admin:
  • URL: https://upskill-staging.measurequick.com/wp-admin/
• Database Access:
  • Via Cloudways dashboard or MySQL client using the credentials in .env

Development Tools

Syncing Data from Staging

To sync data from the staging server to your local backup directory:

./bin/sync-staging.sh

This script will download WordPress files and a database dump from the staging server, storing them in the backups/ directory.

PHPUnit Testing

PHPUnit is configured for the staging environment:

# Run PHPUnit tests on staging
./bin/run-staging-unit-tests.sh

# Run specific test suite
./bin/run-staging-unit-tests.sh --testsuite unit

# Run tests with coverage report
./bin/run-staging-unit-tests.sh --coverage-html ./coverage-report

Refer to staging-phpunit-setup.md for detailed configuration.

Testing

Refer to the comprehensive Testing Guide for detailed instructions on setting up test environments, running test suites, writing tests, and troubleshooting.

E2E Tests:

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

# Run all E2E tests targeting the staging environment
./bin/run-tests.sh --e2e

Note: The E2E tests are executed locally using this command from the `wordpress-dev/` directory and target the staging environment as configured in `playwright.config.ts`. The command `./tests/run-tests.sh pw` is outdated and should not be used.
**[UPDATE 2025-04-29]**  
The correct command to run all Playwright E2E tests is now:
```bash
npx playwright test --config=playwright.config.ts --reporter=list

This supersedes any previous instructions using other Playwright test commands.

[UPDATE 2025-05-18] Implemented comprehensive trainer journey test suite with Page Object Model:

• Complete test coverage for trainer journey steps 1-8
• Page objects for all trainer-facing pages
• Centralized test data management
• Run with: ./bin/run-tests.sh --trainer-journey

The trainer journey tests now provide complete coverage of Steps 1-5:

• ✅ Login & Authentication (Steps 1-2)
• ✅ Dashboard Access (Step 3)
• ✅ Event Management (Step 4a-4d): Create, view, modify, and delete events
• ✅ Event Statistics & Details (Step 5)

Key findings:

• Events created during testing appear in My Events page but not main dashboard
• Form submission requires careful handling of TinyMCE editor and field formatting
• Tests handle both iframe and textarea fallbacks for description field

[UPDATE 2025-05-19] Enhanced event creation testing with improved handling of The Events Calendar Community Events:

• ✅ Identified correct form field names and structure for event creation
• ✅ Implemented Breeze cache clearing script to ensure fresh test runs
• ✅ Created multiple test approaches for handling TinyMCE editor
• 🔧 Event creation form validation issue remains for description field

[UPDATE 2025-05-22] Implemented comprehensive help system and fixed critical dashboard issues:

• ✅ Added interactive welcome guide modal with 4 cards and cookie-based dismissal
• ✅ Implemented tooltips system across all custom pages
• ✅ Created comprehensive documentation page with FAQs and step-by-step guides
• ✅ Fixed dashboard navigation (removed duplicate 'My Events' and 'Help' buttons)
• ✅ Fixed 'Create Event' page showing shortcode instead of form
• ✅ Fixed 'Certificate Reports' critical error causing page crashes
• ✅ Created comprehensive E2E test suite for help system (40+ test cases)

Help System Test Commands:

# Run all help system tests
npx playwright test tests/e2e/help-system-*.test.ts

# Run specific help system components
npx playwright test tests/e2e/help-system-welcome-guide.test.ts
npx playwright test tests/e2e/help-system-tooltips.test.ts
npx playwright test tests/e2e/help-system-documentation.test.ts
npx playwright test tests/e2e/help-system-integration.test.ts

Test infrastructure improvements:

• Created bin/clear-breeze-cache.sh for cache management
• Added form inspection utilities to identify exact field selectors
• Implemented screenshot capture for debugging form submissions
• Multiple test files demonstrating different approaches to form filling

Current status:

• Event creation tests properly fill all required fields
• TinyMCE description field handling works via iframe and JavaScript injection
• Server-side validation appears to reject description despite content being present
• Help system fully functional with comprehensive test coverage
• Dashboard navigation cleaned up and optimized

**Staging Environment Tests:**
```bash
# Configure staging test environment
./bin/configure-staging-tests.sh

# Run unit tests on staging
./bin/run-staging-unit-tests.sh

# Run all test suites on staging
./bin/run-staging-tests.sh

# Run specific test on staging
./bin/run-staging-unit-tests.sh --filter=test_get_total_events_count

Important Notes:

• Some tests may be skipped in staging due to environment differences
• E2E tests target the staging URL defined in .env
• Database operations use staging credentials
• File paths must match staging server structure

WP-CLI

WP-CLI is available on the staging server via SSH:

# Run WP-CLI commands on staging
sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "cd $UPSKILL_STAGING_PATH && wp plugin list"

Database Operations

# Test database connection
mysql -h "$UPSKILL_STAGING_IP" -u "$UPSKILL_STAGING_DB_USER" -p"$UPSKILL_STAGING_DB_PASSWORD" "$UPSKILL_STAGING_DB_NAME" -e "SELECT 1"

# Verify database configuration
./bin/verify-staging.sh --database

Logs and Monitoring

# View WordPress debug logs
sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "tail -f $UPSKILL_STAGING_PATH/wp-content/debug.log"

# View PHP error logs
sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "tail -f /var/log/php-fpm/www-error.log"

Troubleshooting

Staging Environment Issues

1. SSH Connection Issues

   # Test SSH connection
   sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "echo 'Connection successful'"
   
   # Verify environment variables
   env | grep UPSKILL_STAGING
   

2. Database Connection Issues

   # Test database connection
   mysql -h "$UPSKILL_STAGING_IP" -u "$UPSKILL_STAGING_DB_USER" -p"$UPSKILL_STAGING_DB_PASSWORD" "$UPSKILL_STAGING_DB_NAME" -e "SELECT 1"
   
   # Check database credentials
   ./bin/verify-staging.sh
   

3. Test Environment Issues

   # Reconfigure test environment
   ./bin/configure-staging-tests.sh
   
   # Check test configuration
   ./bin/verify-staging.sh
   
   # View test logs
   sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "tail -f $UPSKILL_STAGING_PATH/wp-content/debug.log"
   

4. Deployment Issues

   # Verify file permissions
   ./bin/verify-staging.sh --permissions
   
   # Deploy configuration
   ./bin/deploy-config-staging.sh
   
   # Check deployment status
   ./bin/verify-staging.sh --deployment
   

5. Backup Issues

   # Check available backups
   ls -la backups/
   
   # Create a new backup
   ./bin/sync-production-fixed.sh
   

6. WordPress Access Issues

   # Check if WordPress is accessible
   curl -I "$UPSKILL_STAGING_URL"
   
   # Check WordPress status via SSH
   sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "cd $UPSKILL_STAGING_PATH && wp core is-installed"
   

Debug Mode

WordPress debug mode is enabled by default in the staging environment. Debug logs can be viewed with:

# View debug logs
sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "tail -f $UPSKILL_STAGING_PATH/wp-content/debug.log"

Common Staging Problems and Solutions

Problem	Solution
Search Engine Indexing	Use robots.txt file or meta tags to prevent staging site indexing
Staging Sites Sending Emails	Configure email redirection to prevent staging emails going to customers
Problems with Licensing	Check software provider's licensing policies for staging environments
Overwriting Live Data	Use selective push/pull to avoid overwriting critical data

Best Practices for Staging Sites

1. Take full backups before making significant changes
2. Clear cache when changing code
3. Keep production database separate from testing database
4. Restrict public access to staging environment
5. Use staging-specific configuration for sensitive services

Security Notes

1. Never commit .env to version control
2. Use WordPress Application Passwords for API access
3. Keep production credentials secure
4. Regularly rotate passwords and tokens
5. Keep SSL certificates secure

Support

For issues:

1. Check debug logs
2. Review server logs
3. Verify environment configuration
4. Contact development team:
   • Email: support@tealmaker.com
   • Slack: #network-events-support

Last Updated: April 23, 2025

Test User Setup (Staging)

To create or update the default test persona (test_trainer), run:

./bin/setup-staging-test-users.sh

• User: test_trainer
• Password: Configured via environment variables
• Role: trainer
• This script is idempotent and will update the user if it already exists.

Playwright E2E Test Artifacts

• Logs, screenshots, videos, and trace files are saved in test-results/ after each run.
• Markdown and JSON summaries are generated for each test run.
• If E2E tests fail due to missing elements or URL mismatches, check:
  • That all plugins are activated on staging.
  • That selectors use flexible matching (e.g., expect.stringContaining()).
  • That the staging URL is correctly set in playwright.config.ts.

PHPUnit Persona Management

• Use the HVAC_Test_User_Factory class in your tests to create, update, and clean up test personas.
• See tests/HVAC_Test_User_Factory_Test.php for usage examples.

Get Server Logs Example

# Get the last 50 lines of the debug log
ssh -o StrictHostKeyChecking=no roodev@146.190.76.204 "cd /home/974670.cloudwaysapps.com/uberrxmprk/public_html && tail -n 50 wp-content/debug.log"