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

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

  ```bash
  UPSKILL_STAGING_URL=https://wordpress-974670-5399585.cloudwaysapps.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
```bash
# Deploy configuration to staging
./bin/deploy-config-staging.sh

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

### 2. Testing Setup
```bash
# 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:

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

The script creates a user with the username `test_trainer` and password `Test123!`.
### 3. Data Synchronization
```bash
# 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:

```bash
# 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://wordpress-974670-5399585.cloudwaysapps.com/
- WordPress Admin: 
  - URL: https://wordpress-974670-5399585.cloudwaysapps.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:

```bash
./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:

```bash
# 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](docs/staging-phpunit-setup.md) for detailed configuration.

### Testing

Refer to the comprehensive **[Testing Guide](./testing.md)** for detailed instructions on setting up test environments, running test suites, writing tests, and troubleshooting.

**E2E Tests:**
```bash
# 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
```

**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:
```bash
# 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

```bash
# 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

```bash
# 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**
   ```bash
   # 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**
   ```bash
   # 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**
   ```bash
   # 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**
   ```bash
   # 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**
   ```bash
   # Check available backups
   ls -la backups/
   
   # Create a new backup
   ./bin/sync-production-fixed.sh
   ```

6. **WordPress Access Issues**
   ```bash
   # 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:

```bash
# 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:
```bash
./bin/setup-staging-test-users.sh
```
- User: `test_trainer`
- Password: `Test123!`
- 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
``` bash
# 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"
````