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

PHPUnit Staging Environment Setup Plan

Objective

Configure PHPUnit correctly in the staging environment to enable comprehensive test execution.

Current Status

• PHPUnit 9.6 is correctly specified in composer.json
• Autoload configuration for Tests namespace exists
• Some scripts already using vendor path
• Need standardized approach for command execution

Implementation Plan

graph TD
    A[Start] --> B[1. Script Updates]
    B --> C[2. Environment Configuration]
    C --> D[3. Verification]
    D --> E[4. Documentation]
    E --> F[End]

    subgraph "1. Script Updates"
        B1[Update PHPUnit Command Logic]
        B2[Implement Fallback Mechanism]
        B3[Update All Test Scripts]
    end

    subgraph "2. Environment Configuration"
        C1[Configure PHPUnit Path]
        C2[Verify Composer Settings]
    end

    subgraph "3. Verification"
        D1[Test Both Command Types]
        D2[Verify Fallback Works]
        D3[Run Test Suites]
    end

    subgraph "4. Documentation"
        E1[Update Guides]
        E2[Add Troubleshooting]
    end

1. Script Updates

• Implement PHPUnit command fallback mechanism:

  if command -v phpunit &> /dev/null; then
      PHPUNIT_CMD="phpunit"
  else
      PHPUNIT_CMD="./vendor/bin/phpunit"
  fi
  

• Update the following scripts:

  • run-simplified-tests.sh
  • run-basic-tests.sh
  • run-staging-tests.sh (verify current implementation)

2. Environment Configuration

1. Verify composer.json settings:

   {
     "require-dev": {
       "phpunit/phpunit": "^9.6"
     },
     "autoload-dev": {
       "psr-4": {
         "Tests\\": "tests/"
       }
     }
   }
   

2. Configure PHPUnit path in staging environment:

   export PATH="./vendor/bin:$PATH"
   

3. Verification Steps

1. Test both command methods:

   # Direct command
   phpunit --version
   # Vendor path
   ./vendor/bin/phpunit --version
   

2. Verify fallback mechanism works

3. Execute test suites:

   • Basic tests
   • Simplified tests
   • Staging tests

4. Documentation Updates

1. Update staging restoration guide:

   • Document both PHPUnit command options
   • Explain fallback mechanism
   • Add troubleshooting section

2. Add configuration verification steps:

   • Composer installation check
   • PHPUnit path verification
   • Test execution examples

3. Include common issues and solutions:

   • Command not found
   • Autoloader issues
   • Path configuration problems

Success Criteria

• PHPUnit command accessible via both methods
• Fallback mechanism working correctly
• Test execution scripts running successfully
• All test suites executable in staging environment
• Documentation updated and verified