# Testing Guide

**Status**: Active/Authoritative
**Last Updated**: March 12, 2025
**Superseded By**: [CONSOLIDATED-PLAN.md](CONSOLIDATED-PLAN.md) and [dev-environment-management-plan.md](../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

```bash
# 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

```bash
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:

```php
// 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
```bash
# 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
```bash
./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
```bash
# Install act
brew install act

# Run CI locally
act -j test
```

## Common Issues

1. **Database Connection Issues**
   ```bash
   # Check database container
   docker ps | grep mariadb
   # Reset database
   ./wordpress-dev/manage-env.sh reset-db
   ```

2. **Permission Issues**
   ```bash
   # Fix permissions
   ./wordpress-dev/manage-env.sh fix-permissions
   ```

3. **Test Environment Issues**
   ```bash
   # Reset test environment
   ./wordpress-dev/manage-env.sh reset
   ```