# 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:
```bash
composer require --dev phpunit/phpunit:^9.6
```

2. Required dependencies are already configured in composer.json:
```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:
```bash
phpunit --bootstrap tests/bootstrap-staging.php --testsuite unit
```

2. Using vendor PHPUnit (fallback):
```bash
./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:
```bash
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:
```bash
phpunit --version
# or
./vendor/bin/phpunit --version
```

2. Verify autoloader:
```bash
composer dump-autoload -v
```

3. Test configuration:
```bash
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