CLI Options

Configuration

--bootstrap <file>

Specifies a PHP script that is included before any tests are executed. This is typically used to set up autoloading or initialize the environment required by the test suite.

-c, --configuration <file>

Reads configuration from the specified XML file instead of the default phpunit.xml. This allows you to maintain multiple configuration files for different testing scenarios.

--no-configuration

Ignores the default phpunit.xml configuration file. Useful when you want to run tests without any XML-based configuration being applied.

--extension <class>

Registers a test runner extension by specifying its bootstrap class. The extension will be loaded and activated for the current test run.

--no-extensions

Prevents any test runner extensions from being registered. This disables all extensions, including those configured in the XML configuration file.

--include-path <path(s)>

Prepends PHP’s include_path with the given path or paths. Multiple paths can be specified, separated by the platform’s path separator.

-d <key[=value]>

Sets a php.ini configuration value for the duration of the test run. For boolean settings, the value can be omitted to set it to 1.

--cache-directory <dir>

Specifies the directory where 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 with the --order-by option, for instance)

• 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)

--generate-configuration

Generates a phpunit.xml configuration file with suggested settings through an interactive wizard. This is a convenient way to bootstrap a new PHPUnit configuration.

--migrate-configuration

Migrates an existing XML configuration file to the current format. This is useful after upgrading PHPUnit to a new major version that introduces configuration changes.

--generate-baseline <file>

Generates a baseline file that records currently existing issues such as deprecations and warnings. This baseline can later be used to suppress known issues so that only new issues are reported.

--use-baseline <file>

Uses a previously generated baseline file to suppress known issues during the test run. Issues recorded in the baseline will not be reported.

--ignore-baseline

Ignores any configured baseline file, causing all issues to be reported regardless of whether they appear in the baseline.

Selection

--all

Ignores test selection configured in the XML configuration file and runs all discovered tests. This overrides any <testsuites> filtering from the configuration.

--list-suites

Lists all available test suites defined in the XML configuration file and then exits. No tests are executed.

--testsuite <name>

Restricts test execution to the specified test suite or suites. Multiple suite names can be separated by commas.

--exclude-testsuite <name>

Excludes the specified test suite or suites from the test run. Multiple suite names can be separated by commas.

--list-groups

Lists all available test groups and then exits. No tests are executed.

--group <name>

Only runs tests belonging to the specified group. This option can be used multiple times to select tests from more than one group.

--exclude-group <name>

Excludes tests belonging to the specified group from the test run. This option can be used multiple times to exclude tests from more than one group.

--covers <name>

Only runs tests that declare they intend to cover the specified class or function. This filters based on #[Covers*] attributes. This option can be used multiple times.

--uses <name>

Only runs tests that declare they intend to use the specified class or function. This filters based on #[Uses*] attributes. This option can be used multiple times.

--requires-php-extension <name>

Only runs tests that declare a requirement for the specified PHP extension. Tests without this requirement are skipped.

--list-test-files

Lists all test files that would be executed and then exits. No tests are actually run.

--list-test-ids

Lists all tests that would be executed as test IDs and then exits. A test ID is the fully qualified test name, for example PHPUnit\TestFixture\ExampleTest::testOne. For tests with data sets, a # suffix is appended with the data set index or name, for example PHPUnit\TestFixture\ExampleTest::testOne#0 or PHPUnit\TestFixture\ExampleTest::testOne#named data set.

--list-tests

Lists all tests that would be executed and then exits. Each test is shown with its fully qualified name.

--list-tests-xml <file>

Lists all tests that would be executed in XML format and writes the output to the specified file. No tests are actually run.

--filter <pattern>

Selects tests whose name matches <pattern>. In addition to full PCRE regular expressions, a shortcut syntax is accepted for selecting individual data sets (testFoo#3, testFoo#1-3, testFoo@named set, testFoo#named set). See Filtering by test name for the full syntax.

--exclude-filter <pattern>

The inverse of --filter; accepts the same pattern syntax and removes matching tests from the run.

--test-suffix <suffix>

Restricts test file discovery to files with the specified suffix. The defaults are Test.php and .phpt. This option can be used multiple times.

--test-files-file <file>

Only runs tests from the test files listed in the specified file, with one file path per line. This provides an explicit list of test files to execute.

--run-test-id <test-id>

Only runs the single test identified by <test-id>. Matching is strict and exact. A test ID is the fully qualified test name, for example PHPUnit\TestFixture\ExampleTest::testOne. For tests with data sets, a # suffix is appended with the data set index or name, for example PHPUnit\TestFixture\ExampleTest::testOne#0 or PHPUnit\TestFixture\ExampleTest::testOne#named data set.

--test-id-filter-file <file>

Only runs the tests listed by test ID in the specified file, with one test ID per line. A test ID is the fully qualified test name, for example PHPUnit\TestFixture\ExampleTest::testOne.

Execution

--process-isolation

Runs each test in a separate PHP process. This ensures complete isolation between tests but significantly increases execution time.

--globals-backup

Backs up and restores the $GLOBALS superglobal before and after each test. This prevents tests from inadvertently affecting each other through global state.

--static-backup

Backs up and restores static properties of all classes before and after each test. This prevents tests from affecting each other through shared static state.

--strict-coverage

Enforces strict mode for code coverage metadata. Tests that execute code not declared in their #[Covers*] or #[Uses*] metadata will be marked as risky.

--require-coverage-contribution

Marks tests as risky when they have code coverage targets but do not execute any line of the targeted code.

--strict-global-state

Enforces strict checking of global state changes. Tests that modify global state (such as global variables, super-globals, or static properties) will be marked as risky.

--disallow-test-output

Marks tests that produce output (via echo, print, etc.) as risky. This helps ensure tests only communicate results through assertions.

--enforce-time-limit

Enforces time limits on test execution based on test size. Small tests get 1 second, medium tests get 10 seconds, and large tests get 60 seconds by default.

--default-time-limit <sec>

Sets the timeout in seconds for tests that have no declared size. This is used in conjunction with --enforce-time-limit.

--do-not-report-useless-tests

Suppresses reporting of useless tests. A test is considered useless if it does not perform any assertions.

--stop-on-defect[=<n>]

Stops test execution after the first (or n-th) error, failure, warning, or risky test. This is a shorthand for enabling all specific stop-on options. When used without a value, execution stops after the first defect. When a threshold n is specified, execution stops after n defects have been encountered.

--stop-on-error[=<n>]

Stops test execution after the first (or n-th) test that results in an error.

--stop-on-failure[=<n>]

Stops test execution after the first (or n-th) test that results in a failure.

--stop-on-warning[=<n>]

Stops test execution after the first (or n-th) test that triggers a warning.

--stop-on-risky[=<n>]

Stops test execution after the first (or n-th) test that is considered risky.

--stop-on-deprecation[=<n>]

Stops test execution after the first (or n-th) test that triggers a deprecation.

--stop-on-notice[=<n>]

Stops test execution after the first (or n-th) test that triggers a notice.

--stop-on-skipped[=<n>]

Stops test execution after the first (or n-th) skipped test.

--stop-on-incomplete[=<n>]

Stops test execution after the first (or n-th) incomplete test.

--fail-on-empty-test-suite

Causes PHPUnit to return a failure exit code when no tests were executed. This is useful in CI pipelines to detect misconfigured test suites.

--fail-on-warning

Causes PHPUnit to return a failure exit code when any test triggers a warning.

--fail-on-risky

Causes PHPUnit to return a failure exit code when any test is considered risky.

--fail-on-deprecation

Causes PHPUnit to return a failure exit code when any test triggers a deprecation.

--fail-on-phpunit-deprecation

Causes PHPUnit to return a failure exit code when a PHPUnit deprecation is triggered. PHPUnit deprecations relate to deprecated usage of PHPUnit’s own API.

--fail-on-phpunit-notice

Causes PHPUnit to return a failure exit code when a PHPUnit notice is triggered. PHPUnit notices are informational messages about PHPUnit-specific issues.

--fail-on-phpunit-warning

Causes PHPUnit to return a failure exit code when a PHPUnit warning is triggered.

--fail-on-notice

Causes PHPUnit to return a failure exit code when any test triggers a notice.

--fail-on-skipped

Causes PHPUnit to return a failure exit code when any test is skipped.

--fail-on-incomplete

Causes PHPUnit to return a failure exit code when any test is marked incomplete.

--fail-on-all-issues

Causes PHPUnit to return a failure exit code when any issue is triggered. This is a shorthand that enables all --fail-on-* options at once.

--do-not-fail-on-empty-test-suite

Disables the signaling of failure when no tests were run. This overrides the corresponding XML configuration setting.

--do-not-fail-on-warning

Disables the signaling of failure when a warning is triggered. This overrides the corresponding XML configuration setting.

--do-not-fail-on-risky

Disables the signaling of failure when a test is considered risky. This overrides the corresponding XML configuration setting.

--do-not-fail-on-deprecation

Disables the signaling of failure when a deprecation is triggered. This overrides the corresponding XML configuration setting.

--do-not-fail-on-phpunit-deprecation

Disables the signaling of failure when a PHPUnit deprecation is triggered. This overrides the corresponding XML configuration setting.

--do-not-fail-on-phpunit-notice

Disables the signaling of failure when a PHPUnit notice is triggered. This overrides the corresponding XML configuration setting.

--do-not-fail-on-phpunit-warning

Disables the signaling of failure when a PHPUnit warning is triggered. This overrides the corresponding XML configuration setting.

--do-not-fail-on-notice

Disables the signaling of failure when a notice is triggered. This overrides the corresponding XML configuration setting.

--do-not-fail-on-skipped

Disables the signaling of failure when a test is skipped. This overrides the corresponding XML configuration setting.

--do-not-fail-on-incomplete

Disables the signaling of failure when a test is marked incomplete. This overrides the corresponding XML configuration setting.

--cache-result

Enables writing of test results to the test-results cache file. The result cache is used by the --order-by defects and --order-by duration options to reorder tests based on results of previous test suite runs.

--do-not-cache-result

Disables writing of test results to the test-results cache file. This overrides the corresponding XML configuration setting.

--order-by <order>

Controls the order in which tests are executed. Primary orderings are default, defects, duration-ascending, duration-descending, random, reverse, size-ascending, and size-descending. These can be combined with the dependency modifiers depends and no-depends by separating values with a comma. See The executionOrder Attribute for the full list of accepted combinations. The values duration and size are still accepted as shortcuts for duration-ascending and size-ascending respectively, but are deprecated and will be removed in PHPUnit 14.

--resolve-dependencies

Alias for --order-by depends.

--ignore-dependencies

Alias for --order-by no-depends.

--random-order

Alias for --order-by random.

--random-order-seed <N>

Sets the seed for the random number generator when using --order-by random. Using the same seed produces the same test order, which is useful for reproducing failures.

--reverse-order

Alias for --order-by reverse.

Reporting

--colors=<flag>

Controls the use of colors in terminal output. Accepted values are never, auto (uses colors when the terminal supports it), and always.

--columns <n>

Sets the number of columns to use for progress output. This controls the width of the progress bar displayed during test execution.

--columns max

Uses the maximum number of columns available in the terminal for progress output.

--diff-context <n>

Sets the number of context lines shown around changes in diffs (default: 3). When a test fails and PHPUnit displays the difference between the expected and actual values, this option controls how many unchanged lines are displayed before and after each change to provide context.

--stderr

Writes output to STDERR instead of STDOUT. This can be useful when STDOUT is being redirected or captured.

--no-progress

Disables the progress section of the default output (see Progress). Alternative output formats selected via --testdox, --teamcity, --compact, or --debug are not affected by this option.

--no-results

Disables the test results and summary sections of the default output (see Test results and Summary). Alternative output formats selected via --testdox, --teamcity, --compact, or --debug are not affected by this option.

--no-output

Disables the default output of PHPUnit (runtime information, progress, test results, and summary). Alternative output formats selected via --testdox, --teamcity, --compact, or --debug are not affected by this option and will still produce their own output.

--display-incomplete

Displays details for incomplete tests in the test results. By default, only a count of incomplete tests is shown.

--display-skipped

Displays details for skipped tests in the test results. By default, only a count of skipped tests is shown.

--display-deprecations

Displays details for deprecations triggered by tests. This shows the deprecation messages along with their source location.

--display-phpunit-deprecations

Displays details for PHPUnit deprecations in the test results.

--display-phpunit-notices

Displays details for PHPUnit notices in the test results. These are informational messages from PHPUnit about potential configuration or usage issues.

--display-errors

Displays details for errors triggered by tests. This includes PHP errors such as E_ERROR that occurred during test execution.

--display-notices

Displays details for notices triggered by tests. This shows PHP notice messages along with their source location.

--display-warnings

Displays details for warnings triggered by tests. This shows PHP warning messages along with their source location.

--display-all-issues

Displays details for all types of issues. This is a shorthand that enables all --display-* options at once.

--reverse-list

Prints defects in reverse order. This shows the most recently encountered defects first, which can be useful for large test suites.

--compact

Replaces the default progress and result output with a compact format that omits the progress section, the timing and memory usage line, and color codes. By default only errors, failures, and risky tests are shown in detail; the --display-* options can be used to include additional issues. Compact output can also be activated by setting the PHPUNIT_COMPACT_OUTPUT environment variable to 1. See Compact for details.

--teamcity

Replaces the default progress and result output with TeamCity format. This is used for integration with JetBrains TeamCity and other CI tools that support the TeamCity service message protocol.

--testdox

Replaces the default result output with TestDox format. TestDox renders test method names as human-readable sentences, providing a behavior-driven view of the test suite. To write TestDox output to a file instead, use --testdox-html or --testdox-text (see Logging).

--testdox-summary

Repeats the TestDox output for tests that had errors, failures, or issues at the end of the test run. This provides a focused summary of problematic tests in TestDox format. Requires --testdox.

--debug

Replaces the default progress and result output with detailed debugging information. This shows event-by-event details of the test execution process.

--with-telemetry

Includes telemetry information such as timing and memory usage in the debugging output. This option is used in conjunction with --debug.

Logging

--log-junit <file>

Writes the test results in JUnit XML format to the specified file. This format is widely supported by CI/CD tools for test result reporting.

--log-otr <file>

Writes the test results in Open Test Reporting XML format to the specified file. This is a newer, standardized format for test result reporting.

--include-git-information

Includes Git information (such as branch and commit hash) in the Open Test Reporting XML logfile. This helps associate test results with specific code versions.

--log-teamcity <file>

Writes the test results in TeamCity format to the specified file. This is useful when you need TeamCity-formatted output in a log file while using a different console output format.

--testdox-html <file>

Writes the test results in TestDox format as an HTML file. This produces a browsable, human-readable document of test behaviors. This option is intended for writing a report to a file; for TestDox-formatted console output use --testdox instead.

--testdox-text <file>

Writes the test results in TestDox format as a plain text file. This produces a simple text document of test behaviors. This option is intended for writing a report to a file; for TestDox-formatted console output use --testdox instead.

--log-events-text <file>

Streams all test runner events as plain text to the specified file. This provides a comprehensive log of every event that occurs during the test run.

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

Streams all test runner events as plain text with extended information to the specified file. This includes additional details compared to --log-events-text.

--no-logging

Ignores all logging configured in the XML configuration file. No log files will be written regardless of XML configuration settings.

Code Coverage

--coverage-clover <file>

Writes the code coverage report in Clover XML format to the specified file. This format is supported by many CI tools and code quality platforms.

--coverage-openclover <file>

Writes the code coverage report in OpenClover XML format to the specified file. OpenClover is the open-source continuation of the Clover format.

--coverage-cobertura <file>

Writes the code coverage report in Cobertura XML format to the specified file. This format is commonly used by CI tools such as GitLab CI and Jenkins.

--coverage-crap4j <file>

Writes the code coverage report in Crap4J XML format to the specified file. Crap4J combines code coverage with cyclomatic complexity to identify risky code.

--coverage-html <dir>

Writes the code coverage report in HTML format to the specified directory. This produces a browsable report with line-by-line coverage highlighting.

--coverage-php <file>

Writes serialized code coverage data to the specified file. This data can later be merged with other coverage data or processed programmatically.

--coverage-text[=<file>]

Writes the code coverage report in plain text format. If a file is specified, the report is written there; otherwise it is written to standard output.

--only-summary-for-coverage-text

When generating a text coverage report, only shows the summary without per-class details. This produces a more concise coverage overview.

--show-uncovered-for-coverage-text

When generating a text coverage report, includes files that have no coverage at all. By default, completely uncovered files are omitted from the text report.

--coverage-xml <dir>

Writes the code coverage report in XML format to the specified directory. This generates one XML file per source file along with an index file.

--exclude-source-from-xml-coverage

Excludes the <source> element from the XML coverage report. This reduces the size of the generated XML files by omitting source code.

--warm-coverage-cache

Performs static analysis of tested code and test code ahead of time and stores the result in the code-coverage cache directory. Without this option, the static analysis that is needed for code coverage reporting is performed on the fly during the test suite run and the result is then stored in the cache.

--coverage-filter <dir>

Adds the specified directory to the code coverage filter. Only files within filtered directories will be included in the coverage report.

--path-coverage

Enables path coverage reporting in addition to line coverage. Path coverage tracks which execution paths through the code have been tested, providing deeper insight than line coverage alone.

--disable-coverage-ignore

Disables the @codeCoverageIgnore metadata. When this option is used, code annotated with coverage-ignore metadata will be included in the coverage report.

--no-coverage

Ignores all code coverage reporting configured in the XML configuration file. No coverage data will be collected or reported.

Miscellaneous

-h, --help

Prints the usage information showing all available command-line options and then exits.

--version

Prints the PHPUnit version string and then exits.

--atleast-version <min>

Checks whether the installed PHPUnit version is at least the specified minimum version. Exits with code 0 if the condition is met, or 1 otherwise.

--check-version

Checks whether the installed PHPUnit version is the latest available release. This requires an internet connection to query the latest version information.

--check-php-configuration

Checks whether the current PHP configuration follows best practices for running PHPUnit. Reports any php.ini settings that may cause issues during test execution.