upskill-event-manager/wordpress-dev/tests/e2e/CERTIFICATE_TESTING_GUIDE.md

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)

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

# 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

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