Phpunit Select Config Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

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

   Ensure autoload-dev is dumped:

   composer dump-autoload
   

2. Basic Usage Replace your existing PHPUnit command with:

   ./vendor/bin/phpunit-select-config
   

   The package will automatically detect and prompt you to choose between available phpunit.xml files (e.g., phpunit.xml.dist, phpunit.xml, phpunit.ci.xml).

3. First Use Case Run tests against a specific environment (e.g., CI vs. local):

   ./vendor/bin/phpunit-select-config --env ci
   

   The package will prioritize phpunit.ci.xml if it exists.

Implementation Patterns

Workflow Integration

1. CI/CD Pipelines Hardcode the environment flag in CI scripts (e.g., GitHub Actions):

   - run: ./vendor/bin/phpunit-select-config --env ci
   

   Use phpunit.ci.xml for strict configurations (e.g., no coverage, faster runs).

2. Local Development Default to local config (phpunit.xml) unless overridden:

   ./vendor/bin/phpunit-select-config --env local
   

   Add aliases to composer.json for convenience:

   "scripts": {
     "test": "phpunit-select-config --env local",
     "test:ci": "phpunit-select-config --env ci"
   }
   

3. Multi-Config Projects Name files explicitly (e.g., phpunit.feature.xml, phpunit.unit.xml) and use:

   ./vendor/bin/phpunit-select-config --config feature
   

Laravel-Specific Tips

• Laravel Test Helpers Combine with Laravel’s test helpers (e.g., --env testing):

  ./vendor/bin/phpunit-select-config --env testing --filter TestFeature
  

• Custom Config Paths Override default paths in .phpunit-select-config.php:

  return [
      'paths' => [
          base_path('phpunit.xml'),
          base_path('tests/phpunit.ci.xml'),
      ],
  ];
  

Gotchas and Tips

Pitfalls

1. Missing Config Files If no matching phpunit.xml.* exists, the package defaults to phpunit.xml.dist. Add a fallback:

   ./vendor/bin/phpunit-select-config --fallback
   

2. Case Sensitivity Config file names are case-sensitive on Linux/macOS. Use consistent naming (e.g., phpunit.ci.xml vs. PHPUNIT.CI.XML).

3. Cached Configs PHPUnit caches configs. Clear cache after changing files:

   ./vendor/bin/phpunit-select-config --clear-cache
   

Debugging

• Verbose Mode Enable debug output to see detected configs:

  ./vendor/bin/phpunit-select-config -vvv
  

• Dry Run Test config selection without running tests:

  ./vendor/bin/phpunit-select-config --dry-run
  

Extension Points

1. Custom Logic Extend via .phpunit-select-config.php:

   return [
       'resolver' => function ($env) {
           return base_path("phpunit.{$env}.xml");
       },
   ];
   

2. Environment Variables Use env vars to dynamically select configs:

   ./vendor/bin/phpunit-select-config --env ${TEST_ENV}
   

3. Pre-Commit Hooks Enforce CI configs in pre-commit:

   ./vendor/bin/phpunit-select-config --env ci --filter UnitTest