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

Testing Guide

Status: Active/Authoritative Last Updated: March 12, 2025 Superseded By: CONSOLIDATED-PLAN.md and dev-environment-management-plan.md

This guide covers testing the HVAC Trainer Network Events plugin using our unified test suite.

Test Environment Requirements

Required Plugins

The test environment requires specific plugins with their minimum versions. These plugins should be installed but not updated during testing:

1. The Events Calendar (6.10.2 or higher)
2. The Events Calendar Pro (7.4.2 or higher)
3. Event Tickets (5.19.3 or higher)
4. Event Tickets Plus (6.2.0 or higher)
5. The Events Calendar: Community Events (latest version)
   • Note: Use only 'the-events-calendar-community-events' plugin, not the legacy 'community-events' plugin
6. Spectra Pro (2.0.0 or higher)
7. Premium Starter Templates (4.4.14 or higher)
8. Essential Blocks (5.3.2 or higher)

Important:

• Do not update plugins as part of testing
• Plugin updates should be tested separately
• If you need to test with different plugin versions, use a separate test environment

Quick Start

# Run all tests
./tests/run-tests.sh -t all

# Run specific test types
./tests/run-tests.sh -t unit
./tests/run-tests.sh -t integration
./tests/run-tests.sh -t e2e

# Run with specific browser (for E2E tests)
./tests/run-tests.sh -t e2e --browser firefox

# Run in debug mode
./tests/run-tests.sh -t all --debug

Test Types

Unit Tests

Located in tests/unit/

• Test individual classes and functions
• No WordPress environment required
• Fast execution
• Focus on business logic

Integration Tests

Located in tests/integration/

• Test WordPress-specific functionality
• Requires WordPress test environment
• Tests database interactions
• Tests hooks and filters

E2E Tests

Located in tests/playwright/

• Test complete user journeys
• Requires running WordPress environment
• Tests UI interactions
• Tests real-world scenarios

Test Environment Setup

Prerequisites

• Docker and Docker Compose
• PHP 8.1+
• Node.js 16+ (for E2E tests)
• Composer
• WP-CLI

Test Runner Options

Usage: ./tests/run-tests.sh [options] [test-pattern]

Options:
  -t, --type TYPE       Test type (unit|integration|e2e|all)
  -b, --browser TYPE    Browser for E2E tests (chromium|firefox|webkit)
  -p, --parallel       Run tests in parallel
  --headed             Run E2E tests in headed mode
  --retry N            Number of retries for failed tests
  --debug             Enable debug mode
  --skip-db           Skip database setup
  -v, --verbose       Increase output verbosity
  -h, --help          Show this help message

Writing Tests

Test Utilities

The TestUtils class provides helper functions:

// Create test data
$post = TestUtils::createTestPost();
$user = TestUtils::createTestUser();
$event = TestUtils::createTestEvent();

// Clean up
TestUtils::cleanupTestData();

Best Practices

1. One test class per feature/component
2. Clear test method names
3. Clean up after tests
4. Use meaningful test data
5. Test both positive and negative cases

Test Data Management

Database Management

# Backup test database
./wordpress-dev/manage-env.sh backup-db test_backup

# Restore test database
./wordpress-dev/manage-env.sh restore-db test_backup

Debugging Tests

Debug Mode

./tests/run-tests.sh -t all --debug

Log Files

• WordPress Debug Log: wp-content/debug.log
• Test Results: test-results/
• Diagnostic Results: diagnostic-results/

Continuous Integration

Tests run automatically on:

• Pull requests
• Pushes to main
• Nightly for regression testing

Local CI Testing

# Install act
brew install act

# Run CI locally
act -j test

Common Issues

1. Database Connection Issues

   # Check database container
   docker ps | grep mariadb
   # Reset database
   ./wordpress-dev/manage-env.sh reset-db
   

2. Permission Issues

   # Fix permissions
   ./wordpress-dev/manage-env.sh fix-permissions
   

3. Test Environment Issues

   # Reset test environment
   ./wordpress-dev/manage-env.sh reset