Phpunit Select Config Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev automattic/phpunit-select-config
   

   The binary will be available at vendor/bin/phpunit-select-config.

2. Create Versioned Config Files: Name your PHPUnit config files with a versioned pattern, e.g.:

   phpunit.8.xml.dist
   phpunit.9.xml.dist
   phpunit.10.xml.dist
   

3. First Usage: Run tests with the versioned config pattern:

   ./vendor/bin/phpunit-select-config phpunit.*.xml.dist
   

   The # in the filename will be replaced with the detected PHPUnit major version.

Implementation Patterns

Workflows

1. Local Development: Use a local config pattern (e.g., phpunit.local.*.xml.dist) for environment-specific setups:

   ./vendor/bin/phpunit-select-config phpunit.local.*.xml.dist
   

2. CI/CD Integration: Replace direct phpunit calls in CI scripts with the package:

   # .github/workflows/tests.yml
   - name: Run PHPUnit
     run: ./vendor/bin/phpunit-select-config phpunit.ci.*.xml.dist
   

3. Artisan Command Wrapper: Create a custom Artisan command for Laravel integration:

   // app/Console/Commands/RunVersionedTests.php
   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   use Automattic\PHPUnitSelectConfig\Runner;
   
   class RunVersionedTests extends Command
   {
       protected $signature = 'test:versioned {config=phpunit.xml}';
       protected $description = 'Run PHPUnit with version-specific config';
   
       public function handle()
       {
           $runner = new Runner($this->argument('config'));
           $runner->run();
       }
   }
   

   Register the command in app/Console/Kernel.php:

   protected $commands = [
       Commands\RunVersionedTests::class,
   ];
   

   Usage:

   php artisan test:versioned phpunit.*.xml.dist
   

4. Environment-Based Selection: Use environment variables to dynamically select configs:

   TEST_CONFIG=phpunit.staging.*.xml.dist ./vendor/bin/phpunit-select-config
   

Integration Tips

• Fallback Configs: Ensure a default phpunit.xml exists as a fallback if versioned configs fail to load.
• Parallel Testing: Works seamlessly with PHPUnit’s --parallel flag:

  ./vendor/bin/phpunit-select-config phpunit.*.xml.dist --parallel
  

• Laravel TestCase: No direct conflicts, but ensure versioned configs include Laravel’s test bootstrapping:

  <phpunit>
      <php>
          <ini name="APP_ENV" value="testing"/>
      </php>
      <testsuites>
          <testsuite name="Application Test Suite">
              <directory>./tests/</directory>
          </testsuite>
      </testsuites>
  </phpunit>
  

Gotchas and Tips

Pitfalls

1. Filename Pattern Mismatch:

   • The # in the filename must match the PHPUnit major version exactly (e.g., phpunit.9.xml for PHPUnit 9.x).
   • Debug Tip: Use phpunit-select-config --debug to see the detected version and resolved config path.

2. Missing Config Files:

   • If no matching config file exists, the package will fail silently or use a default. Always validate configs exist in CI:

     ./vendor/bin/phpunit-select-config --dry-run phpunit.*.xml.dist
     

3. Laravel TestCase Conflicts:

   • Versioned configs must include Laravel’s test bootstrapping (e.g., APP_ENV=testing). Omit this, and tests may fail due to missing service providers.
   • Fix: Ensure all versioned configs extend or include Laravel’s default test setup.

4. CI/CD Environment Variables:

   • If using environment variables to select configs (e.g., TEST_CONFIG), ensure the variable is set before running the package:

     # .github/workflows/tests.yml
     env:
         TEST_CONFIG: phpunit.ci.*.xml.dist
     

Debugging

• Verbose Output: Use --verbose to see the resolved config path:

  ./vendor/bin/phpunit-select-config --verbose phpunit.*.xml.dist
  

• Dry Run: Test config resolution without running tests:

  ./vendor/bin/phpunit-select-config --dry-run phpunit.*.xml.dist
  

• Log File: Enable logging for deeper inspection:

  ./vendor/bin/phpunit-select-config --log-file=phpunit.log phpunit.*.xml.dist
  

Extension Points

1. Custom Runner Logic: Extend the Runner class to add pre/post-test hooks:

   use Automattic\PHPUnitSelectConfig\Runner;
   
   class CustomRunner extends Runner
   {
       protected function beforeRun()
       {
           // Custom logic (e.g., setup test environment)
       }
   
       protected function afterRun()
       {
           // Custom logic (e.g., cleanup)
       }
   }
   

2. Dynamic Config Resolution: Override the resolveConfigPath method to implement custom logic (e.g., fetch configs from a remote source):

   protected function resolveConfigPath(string $configPattern): string
   {
       $version = $this->getPhpUnitVersion();
       $path = str_replace('#', $version, $configPattern);
   
       // Custom logic here
       return $path;
   }
   

3. Artisan Integration: For deeper Laravel integration, override the TestWorker in phpunit.xml:

   <phpunit>
       <extensions>
           <extension class="App\Extensions\CustomTestWorker"/>
       </extensions>
   </phpunit>
   

Config Quirks

• Case Sensitivity: Filename patterns are case-sensitive. Use consistent naming (e.g., phpunit.9.xml vs. PHPUNIT.9.XML).

• Dist Files: The package expects .dist files by convention. If using non-.dist files, ensure the pattern matches exactly.

• PHPUnit Version Detection: The package detects the PHPUnit version installed in the project. Ensure your composer.json does not have conflicting PHPUnit versions:

  "require-dev": {
      "phpunit/phpunit": "^9.5 || ^10.0"
  }