upskill-event-manager/wordpress-dev/bin/README-test-data.md

# HVAC Community Events Test Data Generation

This directory contains scripts for generating test data to thoroughly test all features of the HVAC Community Events plugin, including the certificate generation system.

## Available Scripts

### 1. `create-test-data-working.sh` **(Recommended)**

**Purpose:** Creates comprehensive test data for test_trainer including past/future events, tickets, attendees, and certificates.

**What it does:**
- Creates 7 events (4 past, 3 future) with realistic titles, descriptions, and venues
- Varied pricing structure ($200-$500)
- Adds 150+ attendees with realistic data across all events
- Marks 80+ attendees as checked-in for past events
- Generates certificates for all checked-in attendees
- Complete 12-month event lifecycle for realistic dashboard statistics

**Usage:**
```bash
./bin/create-test-data-working.sh
```

**Features to test with this data:**
1. Dashboard statistics (events, tickets, revenue)
2. Event listing (past, upcoming, all)
3. Certificate listing with pagination
4. Filtering by event name
5. Filtering by attendee name/email
6. Filtering by revocation status
7. Certificate download and email functionality

**Note:** This script executes PHP code directly on the server via SSH, avoiding file permission issues with previous scripts.

### 2. `create-complete-test-data.sh` 

**Purpose:** Creates a focused test dataset for certificate testing.

**What it does:**
- Creates 3 new events with realistic titles, descriptions, and venues
- Adds varied attendee data with realistic names and email addresses (58 total)
- Marks most attendees as checked-in (47 total)
- Generates certificates for checked-in attendees (47 total)
- Randomly marks some certificates as revoked (5) or emailed (31)

**Usage:**
```bash
./bin/create-complete-test-data.sh
```

### 2. `run-certificate-helper.sh`

**Purpose:** Processes existing attendees to mark them as checked-in and generate certificates.

**What it does:**
- Goes through existing attendees and randomly marks some as checked-in
- Generates certificates for all checked-in attendees
- Randomly marks some certificates as revoked or emailed

**Usage:**
```bash
./bin/run-certificate-helper.sh
```

### 3. `generate-test-certificates.sh`

**Purpose:** Generates certificates for existing checked-in attendees.

**What it does:**
- Uploads and executes a PHP script on the server
- Generates certificates for all checked-in attendees
- Randomly marks some certificates as revoked or emailed

**Usage:**
```bash
./bin/generate-test-certificates.sh
```

### 4. `add-test-attendees.sh`

**Purpose:** Adds test attendees with check-ins to existing events.

**What it does:**
- Creates PayPal tickets for existing events if needed
- Adds attendees with "Ben Tester" as the first attendee
- Marks a subset of attendees as checked-in
- Sets up required metadata for certificate generation

**Usage:**
```bash
./bin/add-test-attendees.sh
```

### 5. (Legacy) `create-comprehensive-test-data.sh` and others

Several other scripts are available but may encounter issues with the server configuration. The recommended scripts above have been thoroughly tested and confirmed working.

## Testing Workflow

For a complete test of the certificate system:

1. Run the complete test data script:
   ```bash
   ./bin/create-complete-test-data.sh
   ```

2. Visit the certificate reports page to test filtering:
   - https://wordpress-974670-5399585.cloudwaysapps.com/certificate-reports/

3. Test the attendee filtering feature:
   - Try searching by full name (e.g., "Ben Tester")
   - Try searching by partial name (e.g., "Ben" or "Smith")
   - Try searching by email (e.g., "ben@tealmaker.com")
   - Try searching by partial email (e.g., "@gmail.com")

4. Test other filter combinations:
   - Filter by event + attendee
   - Filter by revocation status + attendee
   - Clear filters and verify all certificates are shown

5. Test certificate actions:
   - Download certificate PDFs
   - Test emailing certificates
   - Test revoking certificates
   - Test pagination on certificate reports page

## Certificate Data Structure

The certificate data is stored in the `wp_hvac_certificates` table with the following structure:
- `certificate_id`: Unique identifier
- `event_id`: Associated event
- `attendee_id`: Associated attendee
- `user_id`: Associated WordPress user (if applicable)
- `certificate_number`: Unique formatted number (HVAC-YYYY-XXXXX)
- `file_path`: Path to the PDF file
- `date_generated`: When the certificate was created
- `generated_by`: User who generated the certificate
- `revoked`: Certificate revocation status
- `revoked_date`, `revoked_by`, `revoked_reason`: Revocation details
- `email_sent`: Whether the certificate was emailed
- `email_sent_date`: When the certificate was emailed

## Testing the Attendee Filter

The new attendee filtering feature can be tested with the test data created by these scripts. The filter allows:

1. **Search by attendee name:**
   - Full names like "Ben Tester"
   - Partial names like "John" or "Smith"
   - Case-insensitive matching

2. **Search by attendee email:**
   - Complete emails like "ben@tealmaker.com"
   - Partial email domains like "@gmail.com"
   - Case-insensitive matching

The attendee filter works by performing SQL JOINs with the attendee metadata tables, allowing efficient searching across all certificate records.

## Troubleshooting

### Data Generation Issues

If you encounter issues with the scripts:

1. Check for PHP errors in the output
2. Verify that all required plugins are activated on the server
3. Make sure the certificate table exists in the database
4. Ensure certificate storage directory exists and is writable

For more complex issues, the `test-certificate-system.php` script can be used to diagnose problems with the certificate system.

### Dashboard Shows 0 Events

If the dashboard shows 0 events despite successful data creation:

1. Verify events exist in database:
   ```bash
   # Run on staging server
   wp post list --post_type=tribe_events --author=<user_id>
   ```

2. Check if Events Calendar custom tables are synced:
   ```bash
   # Query occurrences table 
   wp db query "SELECT COUNT(*) FROM wp_tec_occurrences o JOIN wp_posts p ON o.post_id = p.ID WHERE p.post_author = <user_id>"
   ```

3. Debug dashboard data class queries:
   ```bash
   ./bin/debug-dashboard-live.sh
   ```

4. Solution if data exists but doesn't display:
   - The `class-hvac-dashboard-data.php` file uses direct database queries to bypass TEC query modifications
   - Deploy plugin with updated dashboard data class for consistent queries that use `wp_posts` directly

### Login Issues

If test_trainer login fails despite correct credentials:

1. Verify credentials work via wp-cli:
   ```bash
   wp user check-password test_trainer 'password123!'
   ```

2. Reset password:
   ```bash
   wp user update test_trainer --user_pass=password123!
   ```

3. Check and update user capabilities:
   ```bash
   # Check capabilities
   wp user meta get <user_id> wp_capabilities
   
   # Grant required capabilities
   wp eval 'require_once "wp-content/plugins/hvac-community-events/includes/class-hvac-roles.php"; $role = get_role("hvac_trainer"); $role->add_cap("view_hvac_dashboard"); $role->add_cap("manage_hvac_events"); $role->add_cap("read");'
   ```