Php – ny difference in naming the PHPunit configuration file phpunit.xml.dist or phpunit.xml

PHPphpunitsymfonyunit testingxml

Can someone explain to me what is the difference between using PHPunit configuration files named phpunit.xml.dist or phpunit.xml.

The official documentation mentions both names:

PHPUnit's XML configuration file (Appendix C) can also be used to compose a test suite. Example 5.1 shows a minimal phpunit.xml file that will add all *Test classes that are found in *Test.php files when the tests directory is recursively traversed.

with giving phpunit.xml a higher priority when loading configuration without the configuration parameter.

If phpunit.xml or phpunit.xml.dist (in that order) exist in the current working directory and –configuration is not used, the configuration will be automatically read from that file.

I did find some questions (e.g. is this .xml.dist file really required to be used) relating to the fact, that .dist files usually are used as a template (distribution) which should be copied to a version without the .dist ending to activate them (e.g. .htaccess.dist). But this seems not to be the case with PHPunit as it picks up and runs the dist file as well. Other questions (Can I use phpunit.xml for credentials and phpunit.xml.dist for testsuites?) seem to deal with other weird usage ideas about these two files.

In the Symfony world, it is mandatory for reusable bundles to include a phpunit.xml.dist file and I wonder why not a phpunit.xml file instead.

A test suite must not contain AllTests.php scripts, but must rely on the existence of a phpunit.xml.dist file.

So if anyone can shed some light onto this I would be happy 😉

Best Answer

If phpunit.xml or phpunit.xml.dist (in that order) exist in the current working directory and --configuration is not used, the configuration will be automatically read from that file.

The idea behind the fallback (to phpunit.xml.dist when phpunit.xml does not exist) is that phpunit.xml.dist can be checked into version control and phpunit.xml can be ignored from version control. This allows a developer to use a custom configuration without running the risk of accidentally checking it into version control.

Related Topic