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.
[READ ONLY] Run PHPUnit, choosing a configuration file by version. This repository is a mirror, for issue tracking and development head to: https://github.com/automattic/jetpack
Frequently asked questions about Phpunit Select Config
- How does this package help Laravel projects with multiple PHPUnit versions (e.g., PHPUnit 8 for Laravel 8 and PHPUnit 10 for Laravel 10)?
- It automatically detects your PHPUnit version and routes tests to the correct config file (e.g., `phpunit.8.xml` or `phpunit.10.xml`) without hardcoding paths. This is especially useful in Laravel monorepos or legacy projects where different branches require different PHPUnit versions. Just install it as a dev dependency and replace `phpunit` commands with `phpunit-select-config`.
- Can I use this with Laravel’s built-in testing tools like `php artisan test` or Pest?
- For Laravel’s Artisan test runner, you’ll need to wrap this package in a custom Artisan command. Pest may not work out-of-the-box since it relies on `phpunit.xml` directly, but you could create a custom Pest runner that delegates to this package. Always test thoroughly with your Laravel TestCase setup to avoid bootstrapping conflicts.
- What’s the recommended naming convention for PHPUnit config files?
- Use `phpunit.{version}.xml` (e.g., `phpunit.8.xml`, `phpunit.10.xml`) or `phpunit.{version}.xml.dist` for distribution files. The package replaces the `{version}` placeholder with the detected PHPUnit major version when running tests. Avoid spaces or special characters in filenames to prevent parsing issues.
- Will this break my existing CI/CD pipeline if I integrate it?
- No, but you should test it in a staging environment first. The package defaults to `phpunit.xml` if no matching versioned config is found, so it won’t fail silently. For CI, use environment variables (e.g., `TEST_CONFIG=phpunit.10.xml`) to override the default selection if needed.
- How do I install and run this package in a Laravel project?
- Run `composer require --dev automattic/phpunit-select-config` to install it. Then replace `phpunit` commands with `./vendor/bin/phpunit-select-config phpunit.#.xml` (e.g., `./vendor/bin/phpunit-select-config phpunit.*.xml`). For Laravel Artisan, create a custom command like `php artisan test:versioned` that calls this package internally.
- Does this package support Laravel’s TestCase and service providers?
- Yes, but test it first. The package doesn’t interfere with Laravel’s TestCase bootstrapping (e.g., service providers, app bindings) as long as your versioned `phpunit.xml` files include the standard Laravel test setup. If you encounter issues, ensure your config files extend Laravel’s default `phpunit.xml` or include the necessary bootstrap paths.
- What happens if the package can’t find a matching PHPUnit config file?
- It falls back to `phpunit.xml` as a default. You can customize this behavior by modifying the package’s source or setting a fallback config in your CI/CD scripts. For production safety, always validate that the expected config files exist before running tests in critical pipelines.
- Is this package maintained, and what are the alternatives if it’s not?
- This is a mirror of Automattic’s Jetpack repo, so maintenance depends on their roadmap. If it’s unmaintained, alternatives include writing a simple Bash script (e.g., `select-phpunit-config`) or using PHPUnit’s `--configuration` flag directly in your CI scripts. For Laravel, you could also explore custom Artisan commands or Laravel packages like `spatie/laravel-test-factories`.
- Can I use this package with Laravel’s Lighthouse or other testing tools?
- Lighthouse, which uses PHPUnit under the hood, *might* work if you configure it to use this package’s selected config file. However, Lighthouse may override PHPUnit settings, so test thoroughly. For Pest, there’s no native support, but you could create a wrapper script that runs Pest with the correct PHPUnit config.
- How do I debug issues if the package fails to select the right config?
- Run the package with `--debug` (if supported) or check the generated PHPUnit command by running `./vendor/bin/phpunit-select-config --dry-run phpunit.#.xml`. Verify your config files exist and follow the naming convention. If stack traces are unclear, add logging to your CI scripts to capture the exact command being executed.
Weaver
How can I help you explore Laravel packages today?