# Certificate Testing Guide

## Overview

This document provides a comprehensive guide for testing the certificate generation and management functionality in the HVAC Community Events plugin. It consolidates all certificate testing approaches and supersedes previous documentation on this topic.

## Testing Architecture

The certificate testing architecture consists of:

1. **Core Components Testing**:
   - Certificate Manager class
   - Certificate Generator class
   - Certificate Security class
   - PDF generation functionality

2. **UI/UX Testing**:
   - Generate Certificates page
   - Certificate Reports page
   - Certificate download and viewing

3. **Integration Testing**:
   - Event Tickets integration
   - User roles and permissions
   - Email functionality

## Certificate Test Pages

The certificate functionality is accessible via two main pages:

1. **Generate Certificates Page**: `/generate-certificates/`
   - Event selection
   - Attendee filtering (all, checked-in, non-checked-in)
   - Certificate generation
   - Success/error handling

2. **Certificate Reports Page**: `/certificate-reports/`
   - Certificate listing and filtering
   - Certificate viewing
   - Certificate emailing
   - Certificate revocation
   - Pagination

## Test Environment Setup

### Prerequisites

- Staging server with WordPress and required plugins
- SSH access to staging server
- Test trainer account with proper permissions
- Test events with attendees (some checked-in, some not)
- `.env` file with proper credentials

### Environment Preparation

Before running tests, ensure:

1. The HVAC Community Events plugin is activated
2. Rewrite rules are flushed
3. Test data is available (events and attendees)

```bash
# Run this to prepare the environment
cd /Users/ben/dev/upskill-event-manager/wordpress-dev
./bin/run-certificate-tests.sh
```

## Testing Methodology

Due to configuration complexities in the Playwright setup for this project, we use a hybrid approach for testing certificates:

### 1. Manual Testing with Guidance

The primary testing approach uses a guided manual testing script:

```bash
# Test certificate generation
./bin/run-certificate-tests.sh generation

# Test certificate reports
./bin/run-certificate-tests.sh reports
```

This will:
- Prepare the environment (plugin activation, rewrite rules)
- Open Chrome to the appropriate URL
- Display step-by-step testing instructions
- Wait for user confirmation after testing

### 2. Test Coverage Areas

#### Certificate Generation Tests

- **Checked-in Attendees**: Verify certificates can be generated for checked-in attendees
- **Non-checked-in Attendees**: Verify handling of non-checked-in attendees (either allow or show error)
- **All Attendees**: Verify "Select All" functionality works correctly
- **Empty Selection**: Verify proper error handling when no attendees are selected
- **Multiple Events**: Verify event selection dropdown works correctly

#### Certificate Management Tests

- **Listing**: Verify certificates appear in the reports page
- **Viewing**: Verify certificate PDFs can be viewed correctly
- **Emailing**: Verify certificates can be emailed to attendees
- **Revocation**: Verify certificates can be revoked with a reason
- **Filtering**: Verify search and filtering functionality
- **Pagination**: Verify pagination works for large numbers of certificates

### 3. Supporting Test Files

While automated tests may encounter configuration issues, the following components are maintained to support future automated testing:

- **Page Objects**:
  - `CertificatePage.ts`: Encapsulates all certificate UI interactions
  
- **Utility Classes**:
  - `Config.ts`: Centralizes environment configuration
  - `CertificateTestData.ts`: Manages test data creation

- **Test Data**:
  - Test events with specified naming patterns
  - Mixed attendee statuses (checked-in and non-checked-in)

## Test Data Management

### Creating Test Events and Attendees

For reliable testing, use the `test-certificate-email.sh` script which creates:
- A test event with the meta field `_test_certificate_event`
- Test attendees with known emails and check-in statuses

```bash
# Create test data
./bin/test-certificate-email.sh
```

### Certificate Test Scenarios

| Scenario ID | Description | Expected Outcome |
|-------------|-------------|------------------|
| GEN-01 | Generate certificates for checked-in attendees | Certificates successfully generated |
| GEN-02 | Generate certificates for non-checked-in attendees | Either error message or certificates generated (implementation-dependent) |
| GEN-03 | Generate certificates for all attendees | Certificates successfully generated |
| REP-01 | View generated certificates | Certificate PDF displays correctly |
| REP-02 | Email certificates to attendees | Email sent successfully, status updated |
| REP-03 | Revoke a certificate | Certificate marked as revoked, reason recorded |
| REP-04 | Filter certificates by event | Only certificates for selected event shown |
| REP-05 | Navigate through certificate pagination | Pagination controls work correctly |

## Troubleshooting

### Common Issues

1. **PDF Generation Issues**
   - Verify PHP has appropriate permissions
   - Check for TCPDF errors in logs
   - Verify upload directory is writable

2. **Email Delivery Problems**
   - Check WordPress email configuration
   - Verify recipient email is valid
   - Check server's ability to send emails

3. **Certificate Security**
   - Verify download URLs are secure and time-limited
   - Check that only authorized users can access certificates

## Certificate System Architecture

For reference, the certificate system includes:

1. **Database Structure**
   - `{prefix}_hvac_certificates` table with certificate records

2. **File Storage**
   - PDFs stored in `wp-content/uploads/certificates/`
   - Secure access via tokenized URLs

3. **Integration Points**
   - Event Tickets: Attendee data and check-in status
   - WordPress Users: For authentication and capabilities
   - Custom Post Types: For managing relationships

## Future Testing Enhancements

1. **Automated Unit Tests**
   - Test certificate manager methods
   - Test security token generation/validation
   - Test PDF generation

2. **API Testing**
   - Test certificate endpoints
   - Test secure download functionality

3. **Load Testing**
   - Test performance with large numbers of certificates
   - Test simultaneous generation requests

---

*This document replaces all previous certificate testing documentation. For historical reference, see archived documents in the repository.*