Configuring PHPUnit (Simple)

PHPUnit has a variety of command line options. Once we have identified a set of command line options that work well, we will quickly get tired of typing them into a command line. Thankfully, PHPUnit offers an XML configuration file.

This configuration file provides the ability to set any of the command line options. It can also be used to set up various aspects of your test environment such as defining variables, setting the include path, setting other PHP configuration options, and more.

How to do it...

1. The following XML code should be placed in phpunit.xml:

   <phpunit
       colors="true"
       strict="true"
       verbose="true"
   >
     <testsuites>
       <testsuite name="Go Fish Test Suite">
         <file>CardTest.php</file>
       </testsuite>
     </testsuites>
   </phpunit>

2. Then we can run the following command:

   $ phpunit

3. We will see that our test case has been run in the colors mode.

How it works...

We are no longer telling the phpunit script which test case to run. When we utilize a configuration file we are able to use that file to modify the behavior of PHPUnit. This allows us to get rid of the command line options.

When the phpunit script runs, it will look for a file in the current directory called phpunit.xml. If this file exists, it will be loaded as a configuration file. You can explicitly specify the configuration file using the following command:

phpunit –c phpunit.xml

In our test file we have enabled the colors, strict, and verbose flags. These are all attributes of the root <phpunit> element. Using the <testsuites> element we also define which test cases will be run.

The <testsuites> element will contain one or more <testsuite> elements. The <testsuite> element should always have a name attribute that gives a short description of the test suite. The <testsuite> element will finally contain one or more <file> or <directory> elements, which define files and directories containing test cases that should be run. You can also specify any number of <exclude> elements that will contain a path that will be ignored when searching for test cases.

There's more...

In our example we are using a single <file> element to load our CardTest.php file. We could just as easily use <directory>. The following <testsuite> element highlights the difference:

<testsuite name="Go Fish Test Suite">
  <directory>.</directory>
</testsuite>

When specifying directories it should be kept in mind that by default, only files in that directory and any child directories with the pattern *Test.php will be loaded. You can change this behavior using the suffix attribute of the <directory> element. So we could also use the following configuration to specify this explicitly:

<testsuite name="Go Fish Test Suite">
  <directory suffix="Test.php">.</directory>
</testsuite>

Additional configurations

There are many other configuration options available in PHPUnit. Some of them we will cover in later recipes. If you would like to explore all of the options you have at your disposal you should view the PHPUnit documentation: http://www.phpunit.de/manual/current/en/appendixes.configuration.html.

Using phpunit.xml.dist

As you continue building a test suite you may find yourself using the phpunit.xml file to handle environment configurations or other types of configurations that may not always be necessary for some developers. Instead of providing a phpunit.xml file, you can provide a phpunit.xml.dist file. PHPUnit will attempt to use this file if a phpunit.xml file is not found in the current directory. This allows you to package a default configuration in phpunit.xml.dist while letting people easily override it by providing their own phpunit.xml file.