ℹ️ This document is part of Potherca's PHPUnit Best Practices

Do not commit the phpunit.xml file

What is it

A developer wants to configure PHPUnit. The developer creates a phpunit.xml file and commits it to the repository.

When another developer (or system) wants to use other settings, the XML file needs to be edited or another XML file needs to be explicitly pointed out (using phpunit --configuration /path/to/other/phpunit.xml).

This makes it possible to ship a sensible configuration with a project. That way tests work "out of the box".

How does it work

Instead of passing flags to phpunit, PHPUnit can read configuration from an XML file.

An file can be explicitly mentioned using the --configuration flag.

if --configuration is not used, PHPUnit will look for a file named phpunit.xml or phpunit.xml.dist (in that order) in the current working directory. If it exists, the configuration will be automatically read from that file.

Why to avoid

It is not uncommon to have different configuration for development, test and production environments.

When a phpunit.xml file is commited to a reporitory, a perfectly valid (and valuable) feature is shut off.

The burden to make configuration possible is shifted to other developers.

This adds overhead for scripted solutions and scenarios where different configuration is desirable.

By allowing the existance of a phpunit.xml file, different variations can be committed to a repository. The version needed for a specific environment can then simply be symlinked, without need to change the phpunit command.

What to do instead

1. Create a phpunit.xml.dist file
2. Add phpunit.xml to .gitignore
3. Commit these changes to the repository

Counter arguments (and response)

• *What's the harm in people just editing the XML file? Besides being a hassle, it adds extra overhead that can easily be avoided. For one thing the XML file can easily be committed by accident. To avoid potential conflicts, developers will have to git stash the changes made to the XML file.

• How often is this realy relevant? Which tests to include or ignore, which bootstrap to use, environmental variables, which things to report (and in which format) are all controlled from the configuration file. For any of these to differ, an edit would be needed.

• Everybody should just use the same settings I do Give people a choice. Don't be an asshole developer.

Where more information can be found

• The PHPUnit manual entry regarding Organizing Tests - https://phpunit.readthedocs.io/en/latest/organizing-tests.html#organizing-tests-xml-configuration
• The PHPUnit manual entry on the XML Configuration File - https://phpunit.readthedocs.io/en/latest/configuration.html

Relevant rule(s)

• It should be easy to configure tests
• It should be easy to get started (things should work out of the box)