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 attribute on the test case class and test method level.

The backupStaticProperties Attribute

Possible values: true or false (default: false)

PHPUnit can optionally backup all static properties 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 BackupStaticProperties attribute 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 cacheDirectory Attribute

This attribute configures the directory in which PHPUnit stores data between test suite runs. The following data is stored in this directory:

• test-results: Results of the previous test suite run (used for reordering tests based on previous defects or duration, for instance; see below)

• code-coverage: Results of static analysis of tested code and test code (only written when code coverage reporting is requested; significantly improves performance of code coverage analysis on subsequent runs)

The cacheResult Attribute

Possible values: true or false (default: true)

This attribute configures the storing of test results in the test-results cache file. This is required for ordering tests by defects, duration, or size with the executionOrder attribute (see The executionOrder Attribute).

Use --do-not-cache-result on the command line or set this attribute to false to prevent the writing of the test-results cache file.

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 controlGarbageCollector Attribute

Possible values: true or false (default: false)

When the PHP runtime automatically performs garbage collection then this may happen in the middle of the preparation (fixture setup) of a test or in the middle of the execution of a test. This can have a negative impact on test execution performance.

Configuring controlGarbageCollector="true" has the following effects:

• Deactivate automatic garbage collection using gc_disable() before the first test is run

• Trigger garbage collection using gc_collect_cycles() before the first test is run

• Trigger garbage collection using gc_collect_cycles() after each n-th test

• Trigger garbage collection after using gc_collect_cycles() after the last test was run

• Activate automatic garbage collection using gc_enable() after the last test was run

The number of tests to execute before garbage collection is triggered is controlled by numberOfTestsBeforeGarbageCollection (see below).

The numberOfTestsBeforeGarbageCollection Attribute

Possible values: integer (default: 100)

Configures the number of tests to execute before garbage collection is triggered (see above).

The requireCoverageMetadata 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 indicate the code it intends to cover using an attribute.

The requireSealedMockObjects 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 seal the mock objects it creates (see Requiring sealed mock objects).

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 stopOnDefect Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after the first error, failure, warning, or risky test.

The stopOnError Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after the first 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 failure.

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 warning.

The stopOnRisky Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after the first risky test.

The stopOnDeprecation Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after first test that triggered a deprecation (E_DEPRECATED, E_USER_DEPRECATED, or PHPUnit deprecation).

The stopOnNotice Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after first test that triggered a notice (E_STRICT, E_NOTICE, or E_USER_NOTICE).

The stopOnSkipped Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after first skipped test.

The stopOnIncomplete Attribute

Possible values: true or false (default: false)

This attribute configures whether the test suite execution should be stopped after first incomplete test.

The failOnAllIssues 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 an issue is triggered.

The failOnEmptyTestSuite 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 the configured test suite is empty.

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 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 failOnDeprecation 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 triggered a deprecation (E_DEPRECATED or E_USER_DEPRECATED).

The failOnPhpunitDeprecation 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 PHPUnit deprecations were triggered.

The failOnPhpunitNotice 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 PHPUnit notices were triggered.

The failOnNotice 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 triggered a notice (E_STRICT, E_NOTICE, or E_USER_NOTICE).

The failOnSkipped 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 skipped.

The failOnIncomplete 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 incomplete.

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 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 beStrictAboutCoverageMetadata 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 to be covered or used using an attribute.

The requireCoverageContribution Attribute

Possible values: true or false (default: false)

This attribute configures whether PHPUnit should mark a test as risky when it has code coverage targets but does not execute any line of the targeted code.

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 diffContext Attribute

Possible values: integer (default: 3)

This attribute configures the number of context lines shown around changes in diffs.

The timeoutForSmallTests Attribute

Possible values: integer (default: 1)

This attribute configures the time limit for tests attributed with Small (in seconds).

The timeoutForMediumTests Attribute

Possible values: integer (default: 10)

This attribute configures the time limit for tests attributed with Medium (in seconds).

The timeoutForLargeTests Attribute

Possible values: integer (default: 60)

This attribute configures the time limit for tests attributed with Large (in seconds).

The defaultTestSuite Attribute

This attribute configures the name of the default test suite.

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* attributes 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-ascending, duration-descending, random, reverse, size-ascending, size-descending (default: default)

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

This attribute configures the order in which tests are executed.

Primary orderings:

• default: ordered in the order in which PHPUnit found the tests (does not use the result cache)

• defects: ordered by defect (errored, failed, warning, incomplete, risky, skipped, unknown, passed), requires enabled result cache

• duration-ascending: ordered by duration (fastest test first, slowest test last), requires enabled result cache

• duration-descending: ordered by duration (slowest test first, fastest test last), requires enabled result cache

• random: ordered randomly

• reverse: ordered as PHPUnit found the tests, then ordered in reverse

• size-ascending: ordered by size (small, medium, large, unknown), also see Small, Medium, and Large

• size-descending: ordered by size in reverse (large, medium, small, unknown)

Dependency modifiers (combined with the primary orderings above via ,):

• depends: order by dependency first (tests without dependencies first, dependent tests last), then apply the remaining orderings

• no-depends: do not order by dependency, then apply the remaining orderings

Valid combinations include depends,defects, depends,duration-ascending, depends,duration-descending, depends,random, depends,reverse, depends,size-ascending, depends,size-descending, and the corresponding no-depends,* variants.

The defects ordering can also be combined with a secondary ordering that is applied within each defect bucket: defects,duration-ascending, defects,duration-descending, defects,random, defects,reverse, defects,size-ascending, defects,size-descending. These can also be prefixed with depends, or no-depends,, for example depends,defects,duration-ascending.

The resolveDependencies Attribute

Possible values: true or false (default: true)

This attribute configures whether dependencies between tests (expressed using the Depends* attributes) 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 testdoxSummary Attribute

Possible values: true or false (default: false)

This attribute configures whether TestDox output for non-successful tests should be repeated after the regular TestDox output.

The displayDetailsOnAllIssues Attribute

Possible values: true or false (default: false)

This attribute configures whether details on all issues should be printed.

The displayDetailsOnIncompleteTests Attribute

Possible values: true or false (default: false)

This attribute configures whether details on incomplete tests should be printed.

The displayDetailsOnSkippedTests Attribute

Possible values: true or false (default: false)

This attribute configures whether details on skipped tests should be printed.

The displayDetailsOnTestsThatTriggerDeprecations Attribute

Possible values: true or false (default: false)

This attribute configures whether details on tests that triggered deprecations should be printed.

The displayDetailsOnPhpunitDeprecations Attribute

Possible values: true or false (default: false)

This attribute configures whether details on PHPUnit deprecations should be printed.

The displayDetailsOnPhpunitNotices Attribute

Possible values: true or false (default: false)

This attribute configures whether details on PHPUnit notices should be printed.

The displayDetailsOnTestsThatTriggerErrors Attribute

Possible values: true or false (default: false)

This attribute configures whether details on tests that triggered errors should be printed.

The displayDetailsOnTestsThatTriggerNotices Attribute

Possible values: true or false (default: false)

This attribute configures whether details on tests that triggered notices should be printed.

The displayDetailsOnTestsThatTriggerWarnings Attribute

Possible values: true or false (default: false)

This attribute configures whether details on tests that triggered warnings should be printed.

The shortenArraysForExportThreshold Attribute

Possible values: integer (default: 0)

This attribute configures whether the export of arrays should be limited to a specified number of elements.

When set to 0 (default) then the export of arrays is not limited.

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. Files and directories can be excluded by using <exclude> child elements.

<phpunitbootstrap="vendor/autoload.php">
<testsuites>
<testsuitename="unit">
<directory>tests/unit</directory>
</testsuite>

<testsuitename="integration"bootstrap="tests/integration/bootstrap.php">
<directory>tests/integration</directory>
</testsuite>

<testsuitename="smoke">
<file>tests/smoke/FirstTest.php</file>
<file>tests/smoke/SecondTest.php</file>
</testsuite>
</testsuites>
</phpunit>

While the <directory> element adds all test classes found in a directory to the test suite, the <file> element adds the test class found in a single file. This is useful when only a few selected files from a directory should be part of a test suite.

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

<testsuites>
<testsuitename="unit">
<directorygroups="foo,bar">tests/foo-bar</directory>
</testsuite>
</testsuites>

The <include> Element

Parent element: <source>

Configures a set of files to be included in the list of the project’s source code files.

<include>
<directorysuffix=".php">src</directory>
</include>

The example shown above instructs PHPUnit to include all source code files with .php suffix in the src directory and its sub-directories.

The <exclude> Element

Parent element: <source>

Configures a set of files to be excluded from the list of the project’s source code files.

<include>
<directorysuffix=".php">src</directory>
</include>

<exclude>
<directorysuffix=".php">src/generated</directory>
<file>src/autoload.php</file>
</exclude>

The example shown above instructs PHPUnit to include all source code files with .php suffix in the src directory and its sub-directories, but to exclude all files with .php suffix in the src/generated directory and its sub-directories as well as the src/autoload.php file.

The <directory> Element

Parent elements: <include>, <exclude>

Configures a directory and its sub-directories for inclusion in or exclusion from the list of the project’s source code files.

The <file> Element

Parent elements: <include>, <exclude>

Configures a file for inclusion in or exclusion from the list of the project’s source code files.

The <deprecationTrigger> Element

Parent element: <source>

Some libraries use a wrapper around PHP’s trigger_error() function such as symfony/deprecation-contracts or doctrine/deprecations. Using such a wrapper adds an additional stack frame that needs to be considered when reporting of the location where a deprecation was triggered.

The <deprecationTrigger> element, together with its child elements <function> and <method> can be used to configure functions or methods, respectively, as deprecation triggers.

<deprecationTrigger>
<function>trigger_deprecation</function>
</deprecationTrigger>

<deprecationTrigger>
<method>DeprecationTrigger::triggerDeprecation</method>
</deprecationTrigger>

The <issueTriggerResolvers> Element

Parent element: <source>

The <issueTriggerResolvers> element can be used to register custom issue trigger resolver classes. An issue trigger resolver allows you to override how PHPUnit determines the caller and callee files when classifying issues (deprecations, notices, warnings) as self, direct, indirect, or test.

This is useful when a framework or library wraps trigger_error() in a way that the <deprecationTrigger> element cannot handle, for instance when the wrapper is a method that requires inspecting the error message or the stack trace arguments to determine the correct caller and callee.

<issueTriggerResolvers>
<issueTriggerResolverclassName="Vendor\FrameworkResolver"/>
</issueTriggerResolvers>

<issueTriggerResolvers>
<issueTriggerResolverclassName="Vendor\FirstResolver"/>
<issueTriggerResolverclassName="Vendor\SecondResolver"/>
</issueTriggerResolvers>

The <ignoreSelfDeprecations> Attribute

Possible values: true or false (default: false)

Ignore deprecations (E_DEPRECATED and E_USER_DEPRECATED) triggered by first-party code in first-party code.

The <ignoreDirectDeprecations> Attribute

Possible values: true or false (default: false)

Ignore deprecations (E_DEPRECATED and E_USER_DEPRECATED) triggered by first-party code in third-party code.

The <ignoreIndirectDeprecations> Attribute

Possible values: true or false (default: false, suggested: true)

Ignore deprecations (E_DEPRECATED and E_USER_DEPRECATED) triggered by third-party code.

The <restrictNotices> Attribute

Possible values: true or false (default: false)

Restricts the reporting of E_STRICT, E_NOTICE, and E_USER_NOTICE errors to the list of the project’s source code files.

The <restrictWarnings> Attribute

Possible values: true or false (default: false)

Restricts the reporting of E_WARNING and E_USER_WARNING errors to the list of the project’s source code files.

The <baseline> Attribute

Possible values: string

The baseline file to be used when running the test suite.

The <ignoreSuppressionOfDeprecations> Attribute

Possible values: true or false (default: false)

Ignore the suppression (using the @ operator) of E_USER_DEPRECATED errors.

The <ignoreSuppressionOfPhpDeprecations> Attribute

Possible values: true or false (default: false)

Ignore the suppression (using the @ operator) of E_DEPRECATED errors.

The <ignoreSuppressionOfErrors> Attribute

Possible values: true or false (default: false)

Ignore the suppression (using the @ operator) of E_USER_ERROR errors.

The <ignoreSuppressionOfNotices> Attribute

Possible values: true or false (default: false)

Ignore the suppression (using the @ operator) of E_USER_NOTICE errors.

The <ignoreSuppressionOfPhpNotices> Attribute

Possible values: true or false (default: false)

Ignore the suppression (using the @ operator) of E_STRICT and E_NOTICE errors.

The <ignoreSuppressionOfWarnings> Attribute

Possible values: true or false (default: false)

Ignore the suppression (using the @ operator) of E_USER_WARNING errors.

The <ignoreSuppressionOfPhpWarnings> Attribute

Possible values: true or false (default: false)

Ignore the suppression (using the @ operator) of E_WARNING errors.

The includeUncoveredFiles Attribute

Possible values: true or false (default: true)

When set to true, all source code files that are configured to be considered for code coverage analysis will be included in the code coverage report(s). This includes source code files that are not executed while the tests are running.

The ignoreDeprecatedCodeUnits Attribute

Possible values: true or false (default: false)

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

The pathCoverage Attribute

Possible values: true or false (default: false)

When set to false, only line coverage data will be collected, processed, and reported.

When set to true, line coverage, branch coverage, and path coverage data will be collected, processed, and reported. This requires a code coverage driver that supports path coverage. Path Coverage is currently only implemented by Xdebug.

The disableCodeCoverageIgnore Attribute

Possible values: true or false (default: false)

This attribute configures whether metadata to ignore code should be ignored.

The <report> Element

Parent element: <coverage>

Configures the code coverage reports to be generated.

<report>
<cloveroutputFile="clover.xml"/>
<coberturaoutputFile="cobertura.xml"/>
<crap4joutputFile="crap4j.xml"threshold="50"/>
<htmloutputDirectory="html-coverage"lowUpperBound="50"highLowerBound="90"/>
<phpoutputFile="coverage.php"/>
<textoutputFile="coverage.txt"showUncoveredFiles="false"showOnlySummary="true"/>
<xmloutputDirectory="xml-coverage"/>
</report>

The <junit> Element

Parent element: <logging>

Configures a test result logfile in JUnit XML format.

The <teamcity> Element

Parent element: <logging>

Configures a test result logfile in TeamCity format.

The <testdoxHtml> Element

Parent element: <logging>

Configures a test result logfile in TestDox HTML format.

The <testdoxText> Element

Parent element: <logging>

Configures a test result logfile in TestDox text format.

The <bootstrap> Element

Parent element: <extensions>

<extensions>
<bootstrapclass="Vendor\ExampleExtensionForPhpunit\Extension"/>
</extensions>

<extensions>
<bootstrapclass="Vendor\ExampleExtensionForPhpunit\Extension">
<parametername="message"value="the-message"/>
</bootstrap>
</extensions>

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 using ini_set().

<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';