# HVAC Community Events Testing Guide

This document provides guidance for running tests in the HVAC Community Events plugin, with a focus on the certificate functionality testing.

## Test Infrastructure

The testing infrastructure uses the following components:

- **Playwright**: For end-to-end (E2E) testing of the UI
- **PHPUnit**: For unit and integration testing of PHP code
- **Shell Scripts**: For test automation and test data generation

## Setting Up the Testing Environment

### Prerequisites

- Node.js 16+
- npm 7+
- Staging environment access (Cloudways)
- SSH access to staging server

### Installation

1. Install dependencies:
   ```bash
   npm install
   ```

2. Install Playwright browsers:
   ```bash
   npx playwright install
   ```

## E2E Testing

The E2E tests use the Page Object Model (POM) pattern:

- `BasePage.ts`: Common functionality for all pages
- `LoginPage.ts`: Login-related actions
- `DashboardPage.ts`: Dashboard actions
- `CertificatePage.ts`: Certificate-specific actions

### Running Certificate Tests

The certificate tests verify the generation and filtering of certificates:

```bash
# Run all certificate tests
npx playwright test tests/e2e/certificates.test.ts

# Run certificate generation test
npx playwright test tests/e2e/certificate-generation-checked-in.test.ts
```

### Using Test Scripts

Several automated test scripts are available in the `bin` directory:

#### Certificate Filter Testing

The `test-certificate-filter.sh` script allows you to test different certificate filter combinations:

```bash
./bin/test-certificate-filter.sh
```

This interactive script lets you:
- Run all certificate filter tests
- Run only event filtering tests
- Run only attendee filtering tests
- Run a custom filter test

#### E2E Test Optimization

The `optimize-e2e-tests.sh` script helps troubleshoot and optimize the E2E testing infrastructure:

```bash
./bin/optimize-e2e-tests.sh
```

This script:
- Checks for Playwright installation issues
- Validates the test directory structure
- Analyzes the Playwright configuration
- Provides recommendations for improvement

## Test Data Generation

To generate test data for certificate testing:

1. Create test events with attendees:
   ```bash
   ./bin/create-test-data-with-checkins.sh
   ```

2. Generate certificates for checked-in attendees:
   ```bash
   ./bin/generate-test-certificates.sh
   ```

3. Verify test data:
   ```bash
   ./bin/verify-certificate-data.sh
   ```

## Testing Best Practices

1. **Test Independence**:
   - Each test should create its own test data
   - Tests should not depend on the state from other tests
   - Clean up test data when possible
   - Use isolated test users for different test suites

2. **Explicit Waits**:
   - Use explicit waits rather than fixed timeouts
   - Wait for specific elements/conditions, not fixed times
   - Use appropriate timeouts for WordPress's slower operations
   - Add logging for long-running operations

3. **Error Handling**:
   - Implement proper error handling in tests
   - Use try/catch blocks for potentially unstable operations
   - Take screenshots on failures for easier debugging
   - Implement comprehensive error message detection

4. **Selector Stability**:
   - Use CSS selectors that are less likely to change
   - Prefer attribute selectors (e.g., `input[name="log"]`) over ID selectors
   - Use multiple selector strategies with fallbacks for critical elements
   - Create debug scripts to verify selectors when UI changes
   - Centralize selectors in page objects for easier maintenance

5. **Resilient Deployment**:
   - Run pre-deployment selector verification tests
   - Implement health check scripts to validate the environment
   - Use canary deployments with automatic rollback on test failures
   - Maintain versioned snapshots of UI components
   - Add comprehensive monitoring of test execution

## Continuous Integration

The tests are configured to run in CI environments:

- `playwright.config.ts`: Contains CI-specific configuration
- Test retries are enabled for CI environments to handle flaky tests
- Detailed reporting is set up for CI environments

## Troubleshooting Common Issues

1. **Timeouts**: If tests are timing out, check network connectivity and server response times.

2. **Selector Issues**: If elements can't be found, check if selectors need updating due to UI changes.
   - Use the `debug-login-page.spec.ts` script to analyze login form structure
   - Use robust attribute selectors (e.g., `input[name="log"]`) instead of ID selectors
   - Implement multiple selector strategies with fallbacks for critical elements
   - Run selector verification tests before and after WordPress updates

3. **Authentication Problems**: Make sure test credentials are correct and the user has appropriate permissions.
   - Use the `bin/create-test-users.sh` script to ensure test users exist with correct roles
   - Verify login form structure with the debug scripts before running main tests
   - Implement robust error message detection in the LoginPage class

4. **Data Dependencies**: Ensure tests handle the case where expected data isn't present.
   - Use data generation scripts to create known test data
   - Implement check-and-create patterns in test setup

5. **Plugin Activation**: Some tests require the plugin to be freshly activated; use the plugin deactivation/activation commands.
   - Run `bin/verify-plugin-status.sh` before tests to ensure plugin is active
   - Consider automating plugin activation as part of test setup

## Testing Certificate Features

The certificate features have dedicated tests:

1. **Certificate Generation**: Tests the process of generating certificates for event attendees.

2. **Certificate Filtering**: Tests filtering certificates by:
   - Event
   - Attendee name/email
   - Combined filters

3. **Certificate Management**: Tests certificate actions like viewing, downloading, and revoking.

For detailed information on certificate testing, see the `tests/e2e/TESTING-STRATEGY.md` file.