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:

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

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

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

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

  volumes:
    # ... other volumes ...
    - ./bin/wp-cli.phar:/usr/local/bin/wp
  

• Restart containers if docker-compose.yml was modified:

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

  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:

    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.

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

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

# 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