upskill-event-manager/docs/staging-phpunit-setup.md

PHPUnit Staging Environment Setup Guide

Overview

This guide documents the PHPUnit configuration in the staging environment, including installation, execution, and troubleshooting steps.

Installation

1. PHPUnit is installed via Composer:

composer require --dev phpunit/phpunit:^9.6

2. Required dependencies are already configured in composer.json:

{
    "require-dev": {
        "phpunit/phpunit": "^9.6",
        "yoast/phpunit-polyfills": "^1.0",
        "wp-phpunit/wp-phpunit": "^6.7",
        "yoast/wp-test-utils": "^1.0"
    },
    "autoload-dev": {
        "psr-4": {
            "HVAC\\Tests\\": "tests/"
        }
    }
}

Test Execution

The test execution scripts now support two methods of running PHPUnit:

1. Using global PHPUnit installation:

phpunit --bootstrap tests/bootstrap-staging.php --testsuite unit

2. Using vendor PHPUnit (fallback):

./vendor/bin/phpunit --bootstrap tests/bootstrap-staging.php --testsuite unit

The system automatically detects which method to use, with vendor path as fallback.

Environment Configuration

1. The WP_PHPUNIT__DIR environment variable is set to:

export WP_PHPUNIT__DIR=$PLUGIN_PATH/vendor/wp-phpunit/wp-phpunit

2. Test results are stored in:

$PLUGIN_PATH/test-results/

Troubleshooting

Common Issues

1. "Command not found" error:

   • Verify Composer installation
   • Check vendor/bin directory exists
   • Ensure correct PATH configuration

2. Autoloader issues:

   • Verify composer.json autoload-dev configuration
   • Run composer dump-autoload
   • Check namespace matches test files

3. Bootstrap file not found:

   • Verify bootstrap-staging.php exists in tests directory
   • Check file permissions
   • Ensure correct path in test execution command

Verification Steps

1. Check PHPUnit installation:

phpunit --version
# or
./vendor/bin/phpunit --version

2. Verify autoloader:

composer dump-autoload -v

3. Test configuration:

phpunit --bootstrap tests/bootstrap-staging.php --testsuite unit --verbose

Support

For additional support or to report issues, please:

1. Check the test output logs in test-output.log
2. Review error messages in the staging environment logs

Recent Updates

April 12, 2025

1. Added vendor path fallback mechanism
2. Updated documentation across all guides
3. Verified configuration in staging environment
4. Added troubleshooting section for common issues

Integration Notes

• PHPUnit configuration is now synchronized across all environments
• Test execution scripts automatically detect and use appropriate PHPUnit installation
• All paths are relative to ensure consistency between environments
• Documentation updated in README.md and MIGRATION_GUIDE.md

3. Contact the development team with specific error details