4. CLI Options

This appendix provides a reference overview of all command-line options supported by PHPUnit’s test runner.

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-run-history: Status and duration of each test from 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.

--validate-configuration

Validates the XML configuration file against the XML schema definition for the current PHPUnit version and then exits. Validation errors are reported with the line numbers on which they occur.

--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. Names separated with + select the tests that are in all of the named groups: --group database+slow only runs the tests that are in the group database and in the group slow. See Filtering by 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. Names separated with + exclude the tests that are in all of the named groups. See Filtering by 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.

--timeout <sec>

Stops the test run after the specified number of seconds of wall-clock time for the entire run, including bootstrapping and loading the test suite. When the limit is exceeded, no further tests are started, the logs are written, the result is printed, and PHPUnit exits with exit code 124. When the pcntl extension is available, the test that is running when the limit is exceeded is aborted and reported as an error. See Limiting the duration of the test run.

--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-self-deprecation

Causes PHPUnit to return a failure exit code when any test triggers a deprecation in first-party code. This option only takes effect when PHPUnit can identify how a deprecation was triggered. See Failing on deprecations based on how they are triggered.

--fail-on-direct-deprecation

Causes PHPUnit to return a failure exit code when any test triggers a deprecation in third-party code that is called from first-party code. This option only takes effect when PHPUnit can identify how a deprecation was triggered. See Failing on deprecations based on how they are triggered.

--fail-on-indirect-deprecation

Causes PHPUnit to return a failure exit code when any test triggers a deprecation in third-party code that is called from third-party code. This option only takes effect when PHPUnit can identify how a deprecation was triggered. See Failing on deprecations based on how they are triggered.

--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. It takes precedence over the fine-grained failOn* attributes of the XML configuration file; only the --do-not-fail-on-* options can disable failing on a specific issue type when it is used.

--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-self-deprecation

Disables the signaling of failure when a deprecation is triggered in first-party code, even when --fail-on-deprecation is used. This overrides the corresponding XML configuration setting. See Failing on deprecations based on how they are triggered.

--do-not-fail-on-direct-deprecation

Disables the signaling of failure when a deprecation is triggered in third-party code that is called from first-party code, even when --fail-on-deprecation is used. This overrides the corresponding XML configuration setting. See Failing on deprecations based on how they are triggered.

--do-not-fail-on-indirect-deprecation

Disables the signaling of failure when a deprecation is triggered in third-party code that is called from third-party code, even when --fail-on-deprecation is used. This overrides the corresponding XML configuration setting. See Failing on deprecations based on how they are triggered.

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

--record-test-run-history

Enables the recording of the status and duration of each test in the test-run-history file. The test run history is used by the --order-by defects, --order-by duration-ascending, and --order-by duration-descending options to reorder tests based on previous test suite runs.

--do-not-record-test-run-history

Disables the recording of the status and duration of each test in the test-run-history file. This overrides the corresponding XML configuration setting. PHPUnit emits a test runner warning when this is combined with --order-by defects or --order-by duration-*, as those cannot work without the test run history.

--warn-when-php-is-not-configured-for-development

Enables the triggering of a test runner warning when PHP is not configured for development (see Configuring PHP for Development). A warning is triggered for each PHP configuration setting that is not configured as recommended. This overrides the corresponding XML configuration setting.

--do-not-warn-when-php-is-not-configured-for-development

Disables the triggering of a test runner warning when PHP is not configured for development. This overrides the corresponding XML configuration setting.

--order-by <order>

Controls the order in which tests are executed. Accepted orders are default, duration-ascending, duration-descending, modified-ascending, modified-descending, random, reverse, size-ascending, and size-descending. Exactly one order can be configured. The order may be followed by ,defects to move the tests that errored or failed during the previous test run to the front, for instance --order-by duration-ascending,defects. --order-by defects can also be used without configuring an order. See Test execution order.

The values depends and no-depends are deprecated, use --resolve-dependencies and --ignore-dependencies instead. Writing defects before the order, and configuring more than one order, are deprecated as well. 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

Reorders tests so that as many dependencies between them, expressed using the Depends* attributes, as possible are resolved. This is the default. This overrides the corresponding XML configuration setting.

--ignore-dependencies

Does not reorder tests to resolve dependencies between them. This overrides the corresponding XML configuration setting.

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

--repeat <N>

Runs each eligible test N times, stopping at the first failure. This helps find flaky tests and stress-test stateful code. PHPT tests are repeated as well. See Repeating Tests. Mutually exclusive with --retry.

--retry <N>

Attempts each eligible test up to N times, stopping at the first success. This helps tolerate flaky tests that cannot be eliminated, while keeping them visible. PHPT tests are retried as well. See Retrying Tests. Mutually exclusive with --repeat.

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

Backward Compatibility

Please note that if you use --display-all-issues then you opt in to printing additional issues in later versions of PHPUnit that will be put under the control of this CLI option. This is not considered to be a break of backward compatibility and rather the expected behaviour of this CLI option.

--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, risky tests, and the errors and warnings reported by PHPUnit itself are shown in detail; the --display-* options can be used to include additional issues, which are otherwise only counted in the summary line. 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.

--without-class-view

Renders the code coverage report in HTML format without the class view. The class view shows code coverage information aggregated by classes, traits, and functions.

--without-file-view

Renders the code coverage report in HTML format without the file view. The file view shows code coverage information organized by directories and files, including line-by-line coverage highlighting.

The class view and the file view cannot both be disabled. When both --without-class-view and --without-file-view are used, PHPUnit emits a warning and renders both views.

--coverage-jsonl <dir>

Writes the code coverage report in JSONL format to the specified directory. This format reports the code that is not covered, together with the mapping of tests to the code they execute, for consumption by tooling. See The Code Coverage Report in JSONL Format.

--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. For each line of code that was executed, this report records the tests that executed it as well as how often each of them executed it (see The <xml> Element).

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

--branch-coverage

Enables branch coverage reporting in addition to line coverage. Branch coverage tracks which branches of the code have been executed. This requires a code coverage driver that supports branch coverage.

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

--disable-coverage-targeting

Disables the attributes that target units of code, such as CoversClass, UsesClass, and CoversNothing. When this option is used, code coverage is collected for every test and is not limited to the targeted units of code.

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

PHP Archive (PHAR) Only

The following options are only available when PHPUnit is used from a PHP Archive (PHAR).

--manifest: Prints the Software Bill of Materials (SBOM) for the PHP archive in plain-text format and then exits.
--sbom: Prints the Software Bill of Materials (SBOM) for the PHP archive in CycloneDX XML format and then exits.
--composer-lock: Prints the composer.lock file that was used to build the PHP archive and then exits.