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

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:

   npm install
   

2. Install Playwright browsers:

   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:

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

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

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

   ./bin/create-test-data-with-checkins.sh
   

2. Generate certificates for checked-in attendees:

   ./bin/generate-test-certificates.sh
   

3. Verify test data:

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