3. Configuration

PHPUnit builds the effective configuration for a test suite run by combining three layers:

1. Built-in defaults that PHPUnit ships with.

2. XML configuration loaded from phpunit.xml (or the file passed to --configuration), applied on top of the defaults.

3. CLI options passed on the command line, applied on top of the XML configuration.

Each layer overrides the previous one for the settings it touches. Settings that a layer does not specify are inherited from the layer below. For example, beStrictAboutCoverageMetadata defaults to false; setting beStrictAboutCoverageMetadata="true" in phpunit.xml turns it on for all runs; passing --strict-coverage turns it on for a single run even when the XML does not enable it.

The tables in this appendix cross-reference the CLI options (see CLI Options) and the XML configuration attributes and elements (see XML Configuration File) that participate in this override model, along with their built-in defaults. Options that do not participate (CLI-only or XML-only) are listed at the end.

Configuration

CLI option	XML setting	Default
--bootstrap <file>	bootstrap attribute on <phpunit>	—
--cache-directory <dir>	cacheDirectory attribute on <phpunit>	—
--cache-result / --do-not-cache-result	cacheResult attribute on <phpunit>	true
--extension <class>	<bootstrap> under <extensions>	(additive)
--include-path <path>	<includePath> under <php>	(additive)
-d <key[=value]>	<ini> under <php>	(additive)
--use-baseline <file>	baseline attribute on <source>	—

Selection

CLI option	XML setting	Default
--testsuite <name>	defaultTestSuite attribute on <phpunit>	—
--group <name>	<group> under <groups><include>	—
--exclude-group <name>	<group> under <groups><exclude>	—

Execution

CLI option	XML setting	Default
--process-isolation	processIsolation attribute on <phpunit>	false
--globals-backup	backupGlobals attribute on <phpunit>	false
--static-backup	backupStaticProperties attribute on <phpunit>	false
--strict-coverage	beStrictAboutCoverageMetadata attribute on <phpunit>	false
--strict-global-state	beStrictAboutChangesToGlobalState attribute on <phpunit>	false
--disallow-test-output	beStrictAboutOutputDuringTests attribute on <phpunit>	false
--do-not-report-useless-tests	beStrictAboutTestsThatDoNotTestAnything attribute on <phpunit> (inverted)	true
--enforce-time-limit	enforceTimeLimit attribute on <phpunit>	false
--default-time-limit <sec>	defaultTimeLimit attribute on <phpunit>	0
--order-by <order>	executionOrder attribute on <phpunit>	default
--random-order	executionOrder = "random"	default
--reverse-order	executionOrder = "reverse"	default
--resolve-dependencies / --ignore-dependencies	resolveDependencies attribute on <phpunit>	true

Stopping on Issues

CLI option	XML setting	Default
--stop-on-defect	stopOnDefect attribute on <phpunit>	false
--stop-on-error	stopOnError attribute on <phpunit>	false
--stop-on-failure	stopOnFailure attribute on <phpunit>	false
--stop-on-warning	stopOnWarning attribute on <phpunit>	false
--stop-on-risky	stopOnRisky attribute on <phpunit>	false
--stop-on-deprecation	stopOnDeprecation attribute on <phpunit>	false
--stop-on-notice	stopOnNotice attribute on <phpunit>	false
--stop-on-skipped	stopOnSkipped attribute on <phpunit>	false
--stop-on-incomplete	stopOnIncomplete attribute on <phpunit>	false

Failing on Issues

CLI option	XML setting	Default
--fail-on-all-issues	failOnAllIssues attribute on <phpunit>	false
--fail-on-empty-test-suite / --do-not-fail-on-empty-test-suite	failOnEmptyTestSuite attribute on <phpunit>	false
--fail-on-warning / --do-not-fail-on-warning	failOnWarning attribute on <phpunit>	false
--fail-on-risky / --do-not-fail-on-risky	failOnRisky attribute on <phpunit>	false
--fail-on-deprecation / --do-not-fail-on-deprecation	failOnDeprecation attribute on <phpunit>	false
--fail-on-phpunit-deprecation / --do-not-fail-on-phpunit-deprecation	failOnPhpunitDeprecation attribute on <phpunit>	false
--fail-on-phpunit-notice / --do-not-fail-on-phpunit-notice	failOnPhpunitNotice attribute on <phpunit>	false
--fail-on-phpunit-warning / --do-not-fail-on-phpunit-warning	failOnPhpunitWarning attribute on <phpunit>	true
--fail-on-notice / --do-not-fail-on-notice	failOnNotice attribute on <phpunit>	false
--fail-on-skipped / --do-not-fail-on-skipped	failOnSkipped attribute on <phpunit>	false
--fail-on-incomplete / --do-not-fail-on-incomplete	failOnIncomplete attribute on <phpunit>	false

Reporting

CLI option	XML setting	Default
--colors=<flag>	colors attribute on <phpunit>	false
--columns <n>	columns attribute on <phpunit>	80
--stderr	stderr attribute on <phpunit>	false
--reverse-list	reverseDefectList attribute on <phpunit>	false
--testdox	testdox attribute on <phpunit>	false
--testdox-summary	testdoxSummary attribute on <phpunit>	false
--display-all-issues	displayDetailsOnAllIssues attribute on <phpunit>	false
--display-incomplete	displayDetailsOnIncompleteTests attribute on <phpunit>	false
--display-skipped	displayDetailsOnSkippedTests attribute on <phpunit>	false
--display-deprecations	displayDetailsOnTestsThatTriggerDeprecations attribute on <phpunit>	false
--display-phpunit-deprecations	displayDetailsOnPhpunitDeprecations attribute on <phpunit>	false
--display-phpunit-notices	displayDetailsOnPhpunitNotices attribute on <phpunit>	false
--display-errors	displayDetailsOnTestsThatTriggerErrors attribute on <phpunit>	false
--display-notices	displayDetailsOnTestsThatTriggerNotices attribute on <phpunit>	false
--display-warnings	displayDetailsOnTestsThatTriggerWarnings attribute on <phpunit>	false

Logging

CLI option	XML setting	Default
--log-junit <file>	<junit outputFile> under <logging>	—
--log-otr <file>	<otr outputFile> under <logging>	—
--include-git-information	includeGitInformation attribute on <logging><otr>	false
--log-teamcity <file>	<teamcity outputFile> under <logging>	—
--testdox-html <file>	<testdoxHtml outputFile> under <logging>	—
--testdox-text <file>	<testdoxText outputFile> under <logging>	—

Code Coverage

CLI option	XML setting	Default
--path-coverage	pathCoverage attribute on <coverage>	false
--disable-coverage-ignore	disableCodeCoverageIgnore attribute on <coverage>	false
--coverage-clover <file>	<clover outputFile> under <coverage><report>	—
--coverage-openclover <file>	<openclover outputFile> under <coverage><report>	—
--coverage-cobertura <file>	<cobertura outputFile> under <coverage><report>	—
--coverage-crap4j <file>	<crap4j outputFile> under <coverage><report>	—
--coverage-html <dir>	<html outputDirectory> under <coverage><report>	—
--coverage-php <file>	<php outputFile> under <coverage><report>	—
--coverage-text[=<file>]	<text outputFile> under <coverage><report>	—
--only-summary-for-coverage-text	showOnlySummary attribute on <coverage><report><text>	false
--show-uncovered-for-coverage-text	showUncoveredFiles attribute on <coverage><report><text>	false
--coverage-xml <dir>	<xml outputDirectory> under <coverage><report>	—
--exclude-source-from-xml-coverage	includeSource attribute on <coverage><report><xml> (inverted)	true

CLI-only Options

The following CLI options have no XML counterpart. They either control the current invocation of the test runner, perform one-shot operations, or suppress parts of the XML configuration.

Configuration selection and one-shot operations:

• -c, --configuration <file>

• --no-configuration

• --no-extensions

• --no-coverage

• --no-logging

• --generate-configuration

• --migrate-configuration

• --generate-baseline <file>

• --ignore-baseline

• --warm-coverage-cache

Test selection and filtering:

• --all

• --testsuite <name> (also overrides the XML defaultTestSuite attribute; see above)

• --exclude-testsuite <name>

• --filter <pattern>

• --exclude-filter <pattern>

• --covers <name>

• --uses <name>

• --requires-php-extension <name>

• --test-suffix <suffix>

Introspection:

• --list-suites

• --list-groups

• --list-tests

• --list-test-files

• --list-tests-xml <file>

Alternative output and event streaming:

• --debug

• --with-telemetry

• --teamcity

• --log-events-text <file>

• --log-events-verbose-text <file>

• --no-output

• --no-progress

• --no-results

Code coverage:

• --coverage-filter <dir>

Miscellaneous:

• --random-order-seed <N>

• -h, --help

• --version

• --atleast-version <min>

• --check-version

• --check-php-configuration

XML-only Settings

The following XML configuration settings have no CLI counterpart and can only be changed by editing the configuration file.

On the <phpunit> element:

• controlGarbageCollector (default: false)

• numberOfTestsBeforeGarbageCollection (default: 100)

• requireCoverageMetadata (default: false)

• timeoutForSmallTests (default: 1)

• timeoutForMediumTests (default: 10)

• timeoutForLargeTests (default: 60)

• extensionsDirectory

• shortenArraysForExportThreshold

Test suite definition:

• The <testsuites> element and its children

Source code configuration:

• The <source> element and all of its attributes and children

Code coverage:

• includeUncoveredFiles attribute on <coverage> (default: true)

• ignoreDeprecatedCodeUnits attribute on <coverage> (default: false)

• <html> color and bound attributes (lowUpperBound, highLowerBound, colorSuccessLow, colorSuccessMedium, colorSuccessHigh, colorWarning, colorDanger, customCssFile)

• threshold attribute on <coverage><report><crap4j> (default: 50)

PHP environment:

• <const> under <php>

• <var> under <php>

• <env> under <php>

• <get> under <php>

• <post> under <php>

• <cookie> under <php>

• <server> under <php>

• <files> under <php>

• <request> under <php>

Extensions:

• <parameter> elements under <extensions><bootstrap>