upskill-event-manager/wordpress-dev/tests/e2e/docs/harmonized-testing.md

Harmonized Testing Approach

This document outlines the harmonized approach for E2E testing in the HVAC Community Events WordPress plugin. The goal is to ensure consistent and reliable testing across all features, including the certificate functionality.

Overview

The testing system uses Playwright for E2E tests and follows a Page Object Model (POM) pattern. This approach simplifies test maintenance, improves code reusability, and enhances test readability.

Key Components

1. Page Objects

Page objects are organized in the tests/e2e/pages/ directory and represent different pages in the application:

• BasePage.ts - Base class with common methods for all pages
• LoginPage.ts - Handles authentication
• DashboardPage.ts - Trainer dashboard functionality
• CreateEventPage.ts - Event creation functionality
• EventSummaryPage.ts - Event summary views
• CertificatePage.ts - Certificate generation and reporting

2. Utilities

Utility classes in tests/e2e/utils/ provide helper functions:

• Config.ts - Centralized configuration settings
• CertificateTestData.ts - Helper for generating certificate test data

3. Test Files

Test files follow these patterns:

• Basic Tests: Simple tests using test() function (e.g., certificate-basic.spec.ts)
• Journey Tests: End-to-end workflows (e.g., trainer-journey-harmonized.test.ts)

Running Tests

Using NPM Scripts

# Run basic certificate tests
npm run test:basic

# Run full trainer journey
npm run test:journey

# Run with debug mode
npm run test:journey:debug

# Run with Playwright UI mode
npm run test:journey:ui

# Generate test report
npm run report

Using Advanced Test Runner

The bin/run-advanced-tests.sh script provides enhanced setup and configuration:

# Run basic certificate tests (default)
./bin/run-advanced-tests.sh

# Run full trainer journey
./bin/run-advanced-tests.sh --test journey

# Run with UI visible
./bin/run-advanced-tests.sh --test journey --headed

# Run with debug mode
./bin/run-advanced-tests.sh --test journey --debug

# Run with Playwright UI inspector
./bin/run-advanced-tests.sh --test journey --ui

# Run all certificate tests
./bin/run-advanced-tests.sh --test all

The script handles:

• Environment variable loading
• Plugin activation verification
• Test user setup
• Cache clearing
• Proper test execution

Best Practices

1. Page Object Pattern

Always use page objects to interact with the UI. This centralizes selectors and interaction logic:

// Good example
const loginPage = new LoginPage(page);
await loginPage.navigate();
await loginPage.login(username, password);

// Avoid direct page interactions in test files
// Bad example
await page.goto('/login');
await page.fill('#username', username);
await page.fill('#password', password);
await page.click('#submit');

2. Configuration Management

Use the Config utility for accessing environment-specific values:

// Good example
await page.goto(Config.loginUrl);

// Avoid hardcoded values
// Bad example
await page.goto('https://example.com/login');

3. Test Isolation

Ensure tests are isolated and don't depend on each other. Each test should set up its own data and clean up afterward when possible.

4. Error Handling

Use try/catch blocks for complex operations and provide meaningful error messages:

try {
  // Complex operation
} catch (error) {
  console.error('Failed to perform operation:', error.message);
  await page.screenshot({ path: 'error-screenshot.png' });
  throw error;
}

Test Organization

Tagging Tests

Use the JSDoc @tag annotation to categorize tests:

/**
 * @description Login functionality test
 * @tag @auth @login
 */
test('User can log in with valid credentials', async ({ page }) => {
  // Test implementation
});

Test Grouping

When possible, use Playwright's test grouping for related tests (except where causing conflicts):

test.describe('Certificate management', () => {
  test('Can generate certificates', async ({ page }) => {
    // Test implementation
  });
  
  test('Can filter certificates', async ({ page }) => {
    // Test implementation
  });
});

Troubleshooting

If you encounter issues with Playwright tests:

1. Try the basic test file first: The certificate-basic.spec.ts file avoids more complex test structures that might cause issues with certain Playwright versions.

2. Run with UI mode: Use --ui or --headed flags to see the test execution visually.

3. Check dependencies: Ensure you're using a consistent version of Playwright. The package.json has been updated to use @playwright/test in devDependencies only with version ^1.52.0.

4. Verify page objects: If selectors have changed, update the page object files accordingly.

Recent Improvements

1. Harmonized Trainer Journey: Created trainer-journey-harmonized.test.ts that works with the latest Playwright version and includes certificate functionality.

2. Consistent Dependencies: Fixed package.json to ensure Playwright dependencies are correctly configured.

3. Advanced Test Runner: Created bin/run-advanced-tests.sh with support for all test scenarios and configuration options.

4. Test Documentation: Added comprehensive documentation for the testing approach.