3. The XML Configuration File

The backupGlobals Attribute

Possible values: true or false (default: false)

PHPUnit can optionally backup all global and super-global variables before each test and restore this backup after each test.

This attribute configures this operation for all tests. This configuration can be overridden using the @backupGlobals annotation on the test case class and test method level.

The backupStaticAttributes Attribute

Possible values: true or false (default: false)

PHPUnit can optionally backup all static attributes in all declared classes before each test and restore this backup after each test.

This attribute configures this operation for all tests. This configuration can be overridden using the @backupStaticAttributes annotation on the test case class and test method level.

The bootstrap Attribute

This attribute configures the bootstrap script that is loaded before the tests are executed. This script usually only registers the autoloader callback that is used to load the code under test.

The cacheResult Attribute

Possible values: true or false (default: true)

This attribute configures the caching of test results. This caching is required for certain other features to work.

The cacheResultFile Attribute

This attribute configures the file in which the test result cache (see above) is stored.

The cacheTokens Attribute

Possible values: true or false (default: false)

This attribute configures the in-memory cache of the token streams that are used for code coverage analysis.

When more than one code coverage report is generated in a single run, enabling this cache will increase memory usage and may reduce the time to generate the reports.

The colors Attribute

Possible values: true or false (default: false)

This attribute configures whether colors are used in PHPUnit’s output.

Setting this attribute to true is equivalent to using the --colors=auto CLI option.

Setting this attribute to false is equivalent to using the --colors=never CLI option.

The columns Attribute

Possible values: integer or string max (default: 80)

This attribute configures the number of columns to use for progress output.

If max is defined as value, the number of columns will be maximum of the current terminal.

The convertDeprecationsToExceptions Attribute

Possible values: true or false (default: false)

This attribute configures whether E_DEPRECATED and E_USER_DEPRECATED events triggered by the code under test are converted to an exception (and mark the test as error).

The convertErrorsToExceptions Attribute

Possible values: true or false (default: true)

This attribute configures whether E_ERROR and E_USER_ERROR events triggered by the code under test are converted to an exception (and mark the test as error).

The convertNoticesToExceptions Attribute

Possible values: true or false (default: true)

This attribute configures whether E_STRICT, E_NOTICE, and E_USER_NOTICE events triggered by the code under test are converted to an exception (and mark the test as error).

The convertWarningsToExceptions Attribute

Possible values: true or false (default: true)

This attribute configures whether E_WARNING and E_USER_WARNING events triggered by the code under test are converted to an exception (and mark the test as error).

The disableCodeCoverageIgnore Attribute

Possible values: true or false (default: false)

This attribute configures whether the @codeCoverageIgnore* annotations should be ignored.

The forceCoversAnnotation Attribute

Possible values: true or false (default: false)

This attribute configures whether a test will be marked as risky (see Unintentionally Covered Code) when it does not have a @covers annotation.

The printerClass Attribute

Default: PHPUnit\TextUI\ResultPrinter

This attribute configures the name of a class that either is PHPUnit\TextUI\ResultPrinter or that extends PHPUnit\TextUI\ResultPrinter. An object of this class is used to print progress and test results.

The printerFile Attribute

This attribute can be used to configure the path to the sourcecode file that declares the class configured with printerClass in case that class cannot be autoloaded.

The processIsolation Attribute

Possible values: true or false (default: false)

This attribute configures whether each test should be run in a separate PHP process for increased isolation.

The stopOnError Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after the first test finished with status “error”.

The stopOnFailure Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after the first test finished with status “failure”.

The stopOnIncomplete Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after the first test finished with status “incomplete”.

The stopOnRisky Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after the first test finished with status “risky”.

The stopOnSkipped Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after the first test finished with status “skipped”.

The stopOnWarning Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after the first test finished with status “warning”.

The stopOnDefect Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after the first test finished with a status “error”, “failure”, “risky” or “warning”.

The failOnRisky Attribute

Possible values: true or false (default: false)

This attribute configures whether the PHPUnit test runner should exit with a shell exit code that indicates failure when all tests are successful but there are tests that were marked as risky.

The failOnWarning Attribute

Possible values: true or false (default: false)

This attribute configures whether the PHPUnit test runner should exit with a shell exit code that indicates failure when all tests are successful but there are tests that had warnings.

The beStrictAboutChangesToGlobalState Attribute

Possible values: true or false (default: false)

This attribute configures whether PHPUnit should mark a test as risky when global state is manipulated by the code under test (or the test code).

The beStrictAboutOutputDuringTests Attribute

Possible values: true or false (default: false)

This attribute configures whether PHPUnit should mark a test as risky when the code under test (or the test code) prints output.

The beStrictAboutResourceUsageDuringSmallTests Attribute

Possible values: true or false (default: false)

This attribute configures whether PHPUnit should mark a test that is annotated with @small as risky when it invokes a PHP built-in function or method that operates on resource variables.

The beStrictAboutTestsThatDoNotTestAnything Attribute

Possible values: true or false (default: true)

This attribute configures whether PHPUnit should mark a test as risky when no assertions are performed (expectations are also considered).

The beStrictAboutTodoAnnotatedTests Attribute

Possible values: true or false (default: false)

This attribute configures whether PHPUnit should mark a test as risky when it is annotated with @todo.

The beStrictAboutCoversAnnotation Attribute

Possible values: true or false (default: false)

This attribute configures whether PHPUnit should mark a test as risky when it executes code that is not specified using @covers or @uses.

The ignoreDeprecatedCodeUnitsFromCodeCoverage Attribute

Possible values: true or false (default: false)

This attribute configures whether code units annotated with @deprecated should be ignored from code coverage.

The enforceTimeLimit Attribute

Possible values: true or false (default: false)

This attribute configures whether time limits should be enforced.

The defaultTimeLimit Attribute

Possible values: integer (default: 0)

This attribute configures the default time limit (in seconds).

The timeoutForSmallTests Attribute

Possible values: integer (default: 1)

This attribute configures the time limit for tests annotated with @small (in seconds).

The timeoutForMediumTests Attribute

Possible values: integer (default: 10)

This attribute configures the time limit for tests annotated with @medium (in seconds).

The timeoutForLargeTests Attribute

Possible values: integer (default: 60)

This attribute configures the time limit for tests annotated with @large (in seconds).

The testSuiteLoaderClass Attribute

Default: PHPUnit\Runner\StandardTestSuiteLoader

This attribute configures the name of a class that implements the PHPUnit\Runner\TestSuiteLoader interface. An object of this class is used to load the test suite.

The testSuiteLoaderFile Attribute

This attribute can be used to configure the path to the sourcecode file that declares the class configured with testSuiteLoaderClass in case that class cannot be autoloaded.

The defaultTestSuite Attribute

This attribute configures the name of the default test suite.

The verbose Attribute

Possible values: true or false (default: false)

This attribute configures whether more verbose output should be printed.

The stderr Attribute

Possible values: true or false (default: false)

This attribute configures whether PHPUnit should print its output to stderr instead of stdout.

The reverseDefectList Attribute

Possible values: true or false (default: false)

This attribute configures whether tests that are not successful should be printed in reverse order.

The registerMockObjectsFromTestArgumentsRecursively Attribute

Possible values: true or false (default: false)

This attribute configures whether arrays and object graphs that are passed from one test to another using the @depends annotation should be recursively scanned for mock objects.

The extensionsDirectory Attribute

When phpunit.phar is used then this attribute may be used to configure a directory from which all *.phar files will be loaded as extensions for the PHPUnit test runner.

The executionOrder Attribute

Possible values: default, defects, depends, no-depends, duration, random, reverse, size

Using multiple values is possible. These need to be separated by ,.

This attribute configures the order in which tests are executed.

The resolveDependencies Attribute

Possible values: true or false (default: true)

This attribute configures whether dependencies between tests (expressed using the @depends annotation) should be resolved.

The testdox Attribute

Possible values: true or false (default: false)

This attribute configures whether the output should be printed in TestDox format.

The noInteraction Attribute

Possible values: true or false (default: false)

This attribute configures whether progress should be animated when TestDox format is used, for instance.

The <testsuite> Element

Parent element: <testsuites>

A <testsuite> element must have a name attribute and may have one or more <directory> and/or <file> child elements that configure directories and/or files, respectively, that should be searched for tests.

<testsuites>
<testsuitename="unit">
<directory>tests/unit</directory>
</testsuite>

<testsuitename="integration">
<directory>tests/integration</directory>
</testsuite>

<testsuitename="edge-to-edge">
<directory>tests/edge-to-edge</directory>
</testsuite>
</testsuites>

Using the phpVersion and phpVersionOperator attributes, a required PHP version can be specified:

<testsuites>
<testsuitename="unit">
<directoryphpVersion="8.0.0"phpVersionOperator=">=">tests/unit</directory>
</testsuite>
</testsuites>

In the example above, the tests from the tests/unit directory are only added to the test suite if the PHP version is at least 8.0.0. The phpVersionOperator attribute is optional and defaults to >=.

The <listener> Element

Parent element: <listeners>

<listeners>
<listenerclass="MyListener"file="/optional/path/to/MyListener.php">
<arguments>
<array>
<elementkey="0">
<string>Sebastian</string>
</element>
</array>
<integer>22</integer>
<string>April</string>
<double>19.78</double>
<null/>
<objectclass="stdClass"/>
</arguments>
</listener>
</listeners>

The XML configuration above corresponds to attaching the $listener object (see below) to the test execution:

$listener = new MyListener(
 ['Sebastian'],
 22,
 'April',
 19.78,
 null,
 new stdClass
);

The <extension> Element

Parent element: <extensions>

<extensions>
<extensionclass="Vendor\MyExtension"/>
</extensions>

<extensionclass="Vendor\MyExtension">
<arguments>
<integer>1</integer>
<integer>2</integer>
<integer>3</integer>
<string>helloworld</string>
<boolean>true</boolean>
<double>1.23</double>
<array>
<elementindex="0">
<string>value1</string>
</element>
<elementindex="1">
<string>value2</string>
</element>
</array>
<objectclass="Vendor\MyPhpClass">
<string>constructorarg1</string>
<string>constructorarg2</string>
</object>
</arguments>
</extension>

The <log> Element

Parent element: <logging>

<logging>
<logtype="coverage-html"target="/tmp/report"lowUpperBound="35"highLowerBound="70"/>
<logtype="coverage-clover"target="/tmp/coverage.xml"/>
<logtype="coverage-php"target="/tmp/coverage.serialized"/>
<logtype="coverage-text"target="php://stdout"showUncoveredFiles="false"/>
<logtype="junit"target="/tmp/logfile.xml"/>
<logtype="testdox-html"target="/tmp/testdox.html"/>
<logtype="testdox-text"target="/tmp/testdox.txt"/>
</logging>

The XML configuration above corresponds to invoking the TextUI test runner with the following options:

• --coverage-html /tmp/report

• --coverage-clover /tmp/coverage.xml

• --coverage-php /tmp/coverage.serialized

• --coverage-text

• > /tmp/logfile.txt

• --log-junit /tmp/logfile.xml

• --testdox-html /tmp/testdox.html

• --testdox-text /tmp/testdox.txt

The lowUpperBound, highLowerBound, and showUncoveredFiles attributes have no equivalent TextUI test runner option.

• lowUpperBound: Maximum coverage percentage to be considered “lowly” covered.

• highLowerBound: Minimum coverage percentage to be considered “highly” covered.

• showUncoveredFiles: Show all whitelisted files in --coverage-text output not just the ones with coverage information.

• showOnlySummary: Show only the summary in --coverage-text output.

The <includePath> Element

Parent element: <php>

This element can be used to prepend a path to the include_path.

The <ini> Element

Parent element: <php>

This element can be used to set a PHP configuration setting.

<php>
<ininame="foo"value="bar"/>
</php>

The XML configuration above corresponds to the following PHP code:

ini_set('foo', 'bar');

The <const> Element

Parent element: <php>

This element can be used to set a global constant.

<php>
<constname="foo"value="bar"/>
</php>

The XML configuration above corresponds to the following PHP code:

define('foo', 'bar');

The <var> Element

Parent element: <php>

This element can be used to set a global variable.

<php>
<varname="foo"value="bar"/>
</php>

The XML configuration above corresponds to the following PHP code:

$GLOBALS['foo'] = 'bar';

The <env> Element

Parent element: <php>

This element can be used to set a value in the super-global array $_ENV.

<php>
<envname="foo"value="bar"/>
</php>

The XML configuration above corresponds to the following PHP code:

$_ENV['foo'] = 'bar';

By default, environment variables are not overwritten if they exist already. To force overwriting existing variables, use the force attribute:

<php>
<envname="foo"value="bar"force="true"/>
</php>

The <get> Element

Parent element: <php>

This element can be used to set a value in the super-global array $_GET.

<php>
<getname="foo"value="bar"/>
</php>

The XML configuration above corresponds to the following PHP code:

$_GET['foo'] = 'bar';

The <post> Element

Parent element: <php>

This element can be used to set a value in the super-global array $_POST.

<php>
<postname="foo"value="bar"/>
</php>

The XML configuration above corresponds to the following PHP code:

$_POST['foo'] = 'bar';

The <cookie> Element

Parent element: <php>

This element can be used to set a value in the super-global array $_COOKIE.

<php>
<cookiename="foo"value="bar"/>
</php>

The XML configuration above corresponds to the following PHP code:

$_COOKIE['foo'] = 'bar';

The <server> Element

Parent element: <php>

This element can be used to set a value in the super-global array $_SERVER.

<php>
<servername="foo"value="bar"/>
</php>

The XML configuration above corresponds to the following PHP code:

$_SERVER['foo'] = 'bar';

The <files> Element

Parent element: <php>

This element can be used to set a value in the super-global array $_FILES.

<php>
<filesname="foo"value="bar"/>
</php>

The XML configuration above corresponds to the following PHP code:

$_FILES['foo'] = 'bar';

The <request> Element

Parent element: <php>

This element can be used to set a value in the super-global array $_REQUEST.

<php>
<requestname="foo"value="bar"/>
</php>

The XML configuration above corresponds to the following PHP code:

$_REQUEST['foo'] = 'bar';