Weave Code
Phpunit Select Config Laravel Package
automattic/phpunit-select-config
Small utility for PHPUnit projects that helps select or switch the PHPUnit configuration file to use when running tests. Handy for repos with multiple phpunit.xml variants (e.g., local vs CI) and scripts that need consistent config selection.
automattic/phpunit-select-config helps you run PHPUnit with the right configuration file when your project has multiple phpunit*.xml variants (for different environments, CI, or test suites). It provides a small CLI utility to select a PHPUnit config and execute tests without manually passing -c each time.
- Auto-detects available
phpunit*.xml/.distconfigs - Interactive selection when more than one config is found
- Runs PHPUnit with the chosen configuration (passes
-cfor you) - Fits well in CI scripts and local developer workflows
- Lightweight helper focused on multi-config test setups
Frequently asked questions about Phpunit Select Config
- How do I use this package to run different PHPUnit configs in Laravel CI pipelines?
- Install the package via Composer, then create a custom Artisan command (e.g., `test:versioned`) that delegates config selection to the package. In your CI (GitHub Actions, GitLab CI, etc.), call `php artisan test:versioned phpunit.xml.ci` with an environment variable to specify the config file. This avoids hardcoding configs in your workflow.
- Will this break Laravel’s built-in TestCase bootstrapping (e.g., service providers, app bindings)?
- No, the package is a thin wrapper around PHPUnit and doesn’t interfere with Laravel’s TestCase setup. However, ensure your `phpunit.xml` files include the necessary Laravel test bootstrapping files (e.g., `vendor/autoload.php`). If issues arise, fall back to Laravel’s default `phpunit.xml` by catching exceptions in your custom command.
- Can I use this with Laravel Pest or Lighthouse instead of PHPUnit?
- This package is designed for PHPUnit only, so it won’t work directly with Pest or Lighthouse. If you’re using Pest, consider a custom script or Pest’s built-in config merging. For Lighthouse, stick to Laravel’s native test configuration or explore alternatives like `phpunit-multi-config` for parallel test execution.
- What Laravel versions does this package support, and does it work with PHP 8.2?
- The package doesn’t explicitly list Laravel version support, but it mirrors Automattic’s internal tooling (Jetpack), which likely targets Laravel 8+. For PHP 8.2, test thoroughly as the package is unmaintained. If compatibility issues arise, fork the repo or use a lightweight custom script to handle config selection.
- How do I handle cases where the specified PHPUnit config file doesn’t exist?
- The package should throw an exception if the config file is missing. In your custom Artisan command, wrap the runner in a try-catch block and default to Laravel’s `phpunit.xml` or a fallback config. Example: `$runner = new Runner($config ?? 'phpunit.xml');` to ensure tests still run even if dynamic selection fails.
- Is this package safe for production use, or should I avoid it due to lack of maintenance?
- Given its unmaintained status (1 star, no recent activity), this package carries risk for production. Mitigate by forking it or replacing it with a simple custom script. For critical projects, avoid dependency on external, unmaintained tools—especially in CI/CD where test reliability is paramount.
- Can I dynamically select PHPUnit configs based on environment variables (e.g., `.env`)?
- Yes, combine this package with Laravel’s `.env` system. In your custom command, fetch the config path from `.env` (e.g., `config('testing.config_path')`) and pass it to the package’s runner. Example: `$config = env('TEST_CONFIG', 'phpunit.xml');` before initializing the `Runner`.
- How does this compare to using PHPUnit’s `--configuration` flag directly?
- This package abstracts config selection logic into Laravel’s Artisan system, making it easier to integrate with Laravel’s ecosystem (e.g., service providers, environment variables). Using `--configuration` directly requires manual CLI handling, which is less flexible for dynamic workflows like CI/CD or feature-flagged tests.
- Will this work in a Laravel monorepo with separate frontend/backend test suites?
- Yes, this is a prime use case. Store frontend/backend-specific configs (e.g., `phpunit.xml.frontend`, `phpunit.xml.backend`) and use the package to select the correct one based on the branch, environment, or a custom flag. Example: `php artisan test:versioned phpunit.xml.{$env('TEST_SUITE')}`.
- How can I test this package locally before deploying to CI?
- Create a custom Artisan command (as shown in the README) and test it locally with different config files. Use Laravel’s `--env` flag to simulate environments: `php artisan test:versioned phpunit.xml.staging --env=staging`. Verify the correct config is loaded by adding a `phpunit.xml` with a unique `<php>` tag (e.g., `<php><env name="TEST_CONFIG" value="staging"/>`) and checking its value in a test.
Weaver
How can I help you explore Laravel packages today?