What means: "Your XML configuration validates against a deprecated schema. Migrate your XML configuration using "--migrate-configuration"!"
When you run PHPUnit in a fresh project or upgrade to version 10, you might encounter the following error message immediately after starting the test suite:
Your XML configuration validates against a deprecated schema. Migrate your XML configuration using "--migrate-configuration"!
This message is not a fatal crash, but it is a deliberate warning from the PHPUnit team signaling that your current configuration file (phpunit.xml) does not conform to the latest XSD schema introduced in version 10. PHPUnit 10 represents a significant architectural shift compared to versions 9 and earlier; the core has been rewritten in PHP rather than being a collection of unit test libraries, and the configuration format has tightened accordingly.
The error occurs because your phpunit.xml file relies on attributes or structures that are no longer supported or have moved in the new schema. Specifically, looking at a typical setup from a vanilla PHP project using PHPUnit 10:
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="vendor/autoload.php"
colors="true"
verbose="true"
stopOnFailure="true">
<testsuites>
<testsuite name="Unit">
<directory suffix="Test.php">./tests/Unit</directory>
</testsuite>
</testsuites>
</phpunit>
In this example, you are using top-level attributes like colors, verbose, and stopOnFailure. In PHPUnit 9 and earlier, these were valid. However, in PHPUnit 10, the schema has changed to discourage or deprecate certain global attributes in favor of specific options defined within the <phpunit> tag itself or via a different structure. The validator checks your file against ./vendor/phpunit/phpunit/phpunit.xsd (referenced by your xsi:noNamespaceSchemaLocation) and immediately flags these legacy attributes as deprecated.
To resolve this, PHPUnit provides a built-in migration tool. Instead of manually rewriting the entire configuration fileâwhich is error-prone and time-consumingâyou should use the dedicated CLI command included with the package:
vendor/bin/phpunit --migrate-configuration
Running this command performs an automated transformation on your phpunit.xml file. It reads your current settings, identifies deprecated attributes, and updates the file to match the new schema requirements while preserving your intent. For instance, it might move global options into a <phpunit/> block or adjust how test suites are defined if necessary.
After running the migration command, you must re-run your tests to ensure the configuration is now valid:
vendor/bin/phpunit
If the migration was successful, the error message will disappear, and PHPUnit will proceed to load your bootstrap file and execute the tests as defined in the updated schema.
Why Migration Matters
Ignoring this warning is technically possible if you are running a single test or using a specific subset of features that don't trigger the validation check immediately. However, relying on deprecated behavior is risky. Future minor versions of PHPUnit 10 may enforce strict mode by default, causing your tests to fail entirely rather than just warning you. This would lead to unexpected breakage in CI/CD pipelines or local development environments.
Furthermore, the new schema allows for better extensibility and clearer documentation of available options. By migrating early, you align with the modern PHPUnit ecosystem, ensuring compatibility with upcoming features and plugins that expect the newer configuration structure.
Trade-offs and Considerations
The migration process is generally safe because it operates on your local file without altering test logic or source code. However, always review the resulting phpunit.xml after migration. While the tool handles standard deprecations, complex configurations involving custom listeners, extensions, or specific coverage settings might require manual inspection to ensure they are correctly placed within the new schema context.
If you are using a framework like Laravel, note that the phpunit.xml file often comes bundled with the vendor installation. In such cases, you might need to copy your custom configuration to a separate location or adjust the path to avoid conflicts, ensuring your migration command targets the correct file intended for your tests.