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

# Testing Guide

**Status**: Active/Authoritative
**Last Updated**: March 28, 2025
**Scope**: Testing the HVAC Community Events plugin

This guide covers setting up the test environment and running tests for the HVAC Community Events plugin using our unified test suite within the Docker environment.

## Test Environment Requirements

### Prerequisites
- Docker and Docker Compose
- Git
- Node.js and npm (for E2E tests)
- Composer

### Required WordPress Plugins
The test environment requires specific plugins with their minimum versions. These plugins are included in the database/files restored by the `setup-from-backup.sh` script and should **not** be updated manually during testing unless specifically testing updates:

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 standard testing.
- Plugin updates should be tested separately in a dedicated environment or branch.

## Test Environment Setup

The test environment relies heavily on the Docker setup defined in `docker-compose.yml` and configuration files mounted via volumes.

### 1. Initial Environment Setup
Ensure the main development environment is set up correctly using the backup restoration script:
```bash
# Run from wordpress-dev directory
./bin/setup-from-backup.sh

# Verify basic setup (optional but recommended)
./bin/verify-simple.sh
```

### 2. Install Composer Dependencies
Install PHP dependencies, including the PHPUnit framework and the WordPress test suite library (`wp-phpunit/wp-phpunit`):
```bash
# Run from wordpress-dev directory
composer install
```
This installs necessary libraries into the `./vendor` directory, which is mounted into the container.

### 3. Configure PHP Memory Limit
The default PHP memory limit might be too low. Ensure it's increased:
- Edit the host file: `wordpress-dev/php.ini/custom.ini`
- Set `memory_limit = 512M` (or higher if needed).
- **Crucially, restart the Docker containers** after modifying this file:
  ```bash
  # Run from wordpress-dev directory
  docker-compose down && docker-compose up -d
  ```

### 4. Configure WP-CLI
WP-CLI is required for some test setup steps and verification. It's made available via a volume mount.
- Ensure `wp-cli.phar` exists in `wordpress-dev/bin/`. If not, download it:
  ```bash
  # Run from wordpress-dev directory
  curl -o bin/wp-cli.phar https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
  chmod +x bin/wp-cli.phar
  ```
- Ensure the following volume mount exists in `docker-compose.yml` under the `wordpress` service:
  ```yaml
  volumes:
    # ... other volumes ...
    - ./bin/wp-cli.phar:/usr/local/bin/wp
  ```
- **Restart containers** if `docker-compose.yml` was modified:
  ```bash
  # Run from wordpress-dev directory
  docker-compose down && docker-compose up -d
  ```
- When running WP-CLI commands inside the container, use the `--allow-root` flag:
  ```bash
  docker-compose exec wordpress wp plugin list --allow-root
  ```

### 5. Configure PHPUnit Test Environment
The PHPUnit environment requires several configuration files to work correctly with WordPress within Docker:

- **`wordpress-dev/phpunit.xml.dist`**:
    - Defines test suites (e.g., `unit`, `integration`).
    - Specifies `tests/bootstrap.php` as the bootstrap file.
    - **Important:** Should *not* contain `<php><const .../></php>` definitions for WordPress constants (like `ABSPATH`, `DB_*`, `WP_TESTS_DIR`), as these are handled by the bootstrap process and config files.

- **`wordpress-dev/wp-tests-config.php`** (Host file):
    - This file *must* exist on the host.
    - It defines the **test database** credentials. Use the `root` user and the password defined in `.env` (`DEV_DB_ROOT_PASSWORD`) for the test DB (`wordpress_test`). `DB_HOST` must be `db`.
    - It **must** define `define( 'ABSPATH', '/var/www/html/' );` because the test installation script needs it.
    - It should *not* define `WP_TESTS_CONFIG_FILE_PATH`.
    - This file is mounted into the container at `/var/www/html/wp-tests-config.php` via `docker-compose.yml`. Ensure the mount exists:
      ```yaml
      volumes:
        # ... other volumes ...
        - ./wp-tests-config.php:/var/www/html/wp-tests-config.php:cached
      ```
      *(Note: `:cached` flag might cause sync issues on some systems; remove if problems persist)*.

- **`wordpress-dev/tests/bootstrap.php`** (Host file):
    - Defines `ABSPATH` early (`define( 'ABSPATH', '/var/www/html/' );`).
    - Locates the `wp-phpunit` library installed by Composer in the `vendor` directory (using `ABSPATH . 'vendor/...'`).
    - Defines `define( 'WP_TESTS_CONFIG_FILE_PATH', ABSPATH . 'wp-tests-config.php' );` to tell the test library where to find the config.
    - Defines `define( 'WP_TESTS_RUNNING', true );` to signal to `wp-config.php` to skip its DB definitions.
    - Includes the main test library bootstrap: `require $_tests_dir . '/includes/bootstrap.php';`.
    - Loads the plugin being tested (`hvac-community-events`) using `tests_add_filter('muplugins_loaded', ...)` and the correct path (`require ABSPATH . 'wp-content/...'`).

- **`wordpress-dev/wordpress/wp-config.php`** (Host file, mounted into container):
    - The main database definitions (`DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_HOST`) **must** be wrapped in `if ( ! defined( 'WP_TESTS_RUNNING' ) ) { ... }` to prevent conflicts with `wp-tests-config.php` during tests.

### 6. Verify Test Database
Ensure the test database (`wordpress_test`) exists and the user (`root`) has access.
```bash
# Run from wordpress-dev directory
# Create DB if it doesn't exist (uses password from .env)
docker-compose exec db mysql -uroot -p"${DEV_DB_ROOT_PASSWORD}" -e "CREATE DATABASE IF NOT EXISTS wordpress_test;"
# Grant privileges (optional, root usually has them)
# docker-compose exec db mysql -uroot -p"${DEV_DB_ROOT_PASSWORD}" -e "GRANT ALL PRIVILEGES ON wordpress_test.* TO 'root'@'%';"
```

### 7. Activate Plugin Under Test
Ensure the `hvac-community-events` plugin is active for integration and E2E tests:
```bash
# Run from wordpress-dev directory
docker-compose exec wordpress wp plugin activate hvac-community-events --allow-root
```

## Running Tests

Use the `run-tests.sh` script located in the `wordpress-dev/bin` directory.

```bash
# Run all test suites (Unit, Integration, E2E)
./bin/run-tests.sh

# Run only Unit tests
./bin/run-tests.sh --unit

# Run only Integration tests
./bin/run-tests.sh --integration

# Run only E2E tests
./bin/run-tests.sh --e2e

# Run specific E2E test suite (e.g., login tests tagged with @login)
./bin/run-tests.sh --login

# Run with debug output
./bin/run-tests.sh --debug
```
**Note:** The script is configured to exit immediately if Unit or Integration tests fail.

## Test Types

### Unit Tests
- **Location:** `wordpress-dev/tests/unit/`
- **Purpose:** Test individual PHP classes and functions in isolation.
- **Environment:** Minimal dependencies, does not require a fully bootstrapped WordPress environment for most tests (though uses `WP_UnitTestCase` which provides some WP functions).
- **Execution:** Fast.

### Integration Tests
- **Location:** `wordpress-dev/tests/integration/`
- **Purpose:** Test functionality that requires interaction with WordPress core, the database, or other plugins (e.g., hooks, filters, options, user roles, CPTs).
- **Environment:** Requires the WordPress test environment loaded via `wp-phpunit`.
- **Execution:** Slower than unit tests.

### E2E (End-to-End) Tests
- **Location:** `wordpress-dev/tests/e2e/`
- **Framework:** Playwright
- **Purpose:** Simulate real user interactions in a browser, testing complete user flows from the frontend.
- **Environment:** Requires the full Docker environment (WordPress, Nginx, DB) to be running and accessible via `http://localhost:8080`.
- **Execution:** Slowest test type.

## Writing Tests

Refer to PHPUnit and Playwright documentation for detailed syntax.

### Best Practices
- One test class per code class/component/feature.
- Use descriptive test method names (e.g., `test_login_redirects_trainer_to_dashboard`).
- Test both expected outcomes (happy path) and error conditions (negative path).
- Make tests independent; the outcome of one test should not affect another.
- Clean up any created data (posts, users, options) in `tearDown()` methods or use WP test factories.

## Troubleshooting Common Issues

1.  **PHPUnit: `wp-tests-config.php is missing!`**
    - Verify `wordpress-dev/wp-tests-config.php` exists on the host.
    - Verify the volume mount `- ./wp-tests-config.php:/var/www/html/wp-tests-config.php` exists in `docker-compose.yml` for the `wordpress` service.
    - Verify `define( 'WP_TESTS_CONFIG_FILE_PATH', ABSPATH . 'wp-tests-config.php' );` is present and correct in `tests/bootstrap.php`.
    - Restart Docker containers (`docker-compose down && docker-compose up -d`).

2.  **PHPUnit: `Constant ... already defined` Warnings**
    - Ensure `<php><const .../></php>` definitions are *removed* from `phpunit.xml.dist`.
    - Ensure the `if ( ! defined( 'WP_TESTS_RUNNING' ) )` check correctly wraps DB definitions in `wordpress/wp-config.php`.
    - Ensure `define( 'WP_TESTS_RUNNING', true );` exists in `tests/bootstrap.php` *before* the main test bootstrap is required.

3.  **PHPUnit: `Undefined constant "ABSPATH"` Fatal Error**
    - Ensure `define( 'ABSPATH', '/var/www/html/' );` exists in `wp-tests-config.php`.
    - Ensure `wp-tests-config.php` is correctly mounted and loaded (see point 1).
    - Ensure the main `wp-phpunit/includes/bootstrap.php` loads `wp-tests-config.php` *before* scripts needing `ABSPATH` (like `install.php` or potentially `mock-mailer.php`) are called. *(Self-correction: We fixed mock-mailer by defining ABSPATH early in our bootstrap, but install.php needs it from wp-tests-config)*.

4.  **PHPUnit: `Access denied for user 'root'@'...' (using password: NO)`**
    - Ensure `DB_PASSWORD` is correctly defined (hardcoded) in `wp-tests-config.php`.
    - Ensure the `if ( ! defined( 'WP_TESTS_RUNNING' ) )` check correctly wraps DB definitions in `wordpress/wp-config.php`.
    - Ensure `wp-tests-config.php` is correctly mounted and loaded (see point 1).
    - Verify the test database (`wordpress_test`) exists and the user (`root`) has privileges.

5.  **PHPUnit: `Could not find tests_dir/includes/functions.php`**
    - Ensure `composer install` was run successfully in `wordpress-dev`.
    - Verify the path calculation for `$_vendor_dir` in `tests/bootstrap.php` is correct (`$_vendor_dir = ABSPATH . 'vendor/wp-phpunit/wp-phpunit';`).
    - Check permissions on the host `vendor` directory if issues persist.
    - Try removing the `:cached` flag from volume mounts in `docker-compose.yml` if sync issues are suspected. Restart containers after changes.

6.  **PHPUnit: `Declaration of ... must be compatible with ...(): void`**
    - Add the `: void` return type hint to the `setUp()` and `tearDown()` methods in your test class.

7.  **WP-CLI: `executable file not found in $PATH`**
    - Ensure `wp-cli.phar` is downloaded to `wordpress-dev/bin/`.
    - Ensure the volume mount `- ./bin/wp-cli.phar:/usr/local/bin/wp` exists in `docker-compose.yml`.
    - Ensure the host file `bin/wp-cli.phar` has execute permissions (`chmod +x`).
    - Restart Docker containers (`docker-compose down && docker-compose up -d`).

8.  **WP-CLI/PHPUnit: `Allowed memory size exhausted`**
    - Increase `memory_limit` in `wordpress-dev/php.ini/custom.ini` (e.g., `512M`).
    - Ensure the volume mount `- ./php.ini/custom.ini:/usr/local/etc/php/conf.d/custom.ini` is correct in `docker-compose.yml`.
    - Restart Docker containers (`docker-compose down && docker-compose up -d`).

9.  **E2E: Timeout waiting for element / 404 errors**
    - Verify the plugin under test (`hvac-community-events`) is active (`docker-compose exec wordpress wp plugin is-active hvac-community-events --allow-root`). Activate if needed.
    - Verify the URL/slug used in `page.goto()` in the Playwright test matches the actual page slug in WordPress containing the shortcode or element.
    - Verify the element selector used in the test matches the actual element ID/class/attribute in the rendered HTML.
    - Check container logs (`docker-compose logs wordpress`, `docker-compose logs nginx`) for PHP or web server errors preventing the page from rendering.

10. **General Docker Issues:**
    - Restart containers: `docker-compose down && docker-compose up -d`
    - Prune system: `docker system prune -a` (Use with caution, removes unused images/volumes/networks)
    - Check Docker Desktop/Engine resource allocation (Memory, CPU).

*Last Updated: March 28, 2025*