PHPUNIT(1)

📦

version 13.2.6 · 7 versions

💅 PHPUNIT — the `phpunit(1)` glow-up

okay bestie, welcome to the phpunit command line interface manual, aka the group chat where your PHP tests come to be seen and judged (lovingly) 👑. This is a User Commands page for PHPUNIT(1), and we're gonna read it together, no skipping. grab a strawberry drink 🍓 and let's go.

✨ SYNOPSIS ✨

phpunit [options] <directory|file> ...

that's it. that's the whole vibe. you point it at directories or files, you sprinkle options, it runs your tests. iconic.

💖 DESCRIPTION 💖

this page is lowkey a mega-list of every option, so I'm breaking it down by the cute little groups the original uses: Configuration, Selection, Execution, Reporting, Logging, and Code Coverage. every single flag stays exactly where it was, promise 🫶

🌸 Configuration 🌸

the "set me up before anything runs" section. getting-ready-with-me energy ✨

--bootstrap <file> — a PHP script that gets included before the tests run. the pre-game ritual.
-c, --configuration <file> — read your configuration from an XML file.
--no-configuration — ignore the default configuration file (phpunit.xml). not me ghosting the default config 🙈.
--extension <class> — register a test runner extension with bootstrap <class>.
--no-extensions — do not register test runner extensions. none. zero. nada.
--include-path <path(s)> — prepend PHP's include_path with the given path(s).
-d <key[=value]> — sets a php.ini value.
--cache-directory <dir> — specify the cache directory.
--generate-configuration — generate a configuration file with suggested settings.
--migrate-configuration — migrate your configuration file to the current format.
--validate-configuration — validate the XML configuration file. vibe check on your config ✅.
--generate-baseline <file> — generate a baseline for issues.
--use-baseline <file> — use a baseline to ignore issues.
--ignore-baseline — do not use a baseline to ignore issues.

🦋 Selection 🦋

which tests actually get to show up to the party 💅

--all — ignore test selection from the XML configuration file.
--list-suites — list available test suites.
--testsuite <name> — only run tests from the specified test suite(s).
--exclude-testsuite <name> — exclude tests from the specified test suite(s).
--list-groups — list available test groups.
--group <name> — only run tests from the specified group(s).
--exclude-group <name> — exclude tests from the specified group(s).
--covers <name> — only run tests that intend to cover <name>.
--uses <name> — only run tests that intend to use <name>.
--requires-php-extension <name> — only run tests that require PHP extension <name>.
--list-test-files — list available test files.
--list-test-ids — list available tests as test IDs.
--list-tests — list available tests.
--list-tests-xml <file> — list available tests in XML format.
--filter <pattern> — filter which tests to run.
--exclude-filter <pattern> — exclude tests for the specified filter pattern.
--test-suffix <suffixes> — only search for tests in files with the specified suffix(es). Default: Test.php,.phpt
--test-files-file <file> — only run test files listed in file (one file by line).
--run-test-id <test-id> — only run the test identified by the specified test ID.
--test-id-filter-file <file> — only run tests listed by test ID in file (one test ID per line).

🔥 Execution 🔥

how the tests actually run. this is where the drama lives 😭

--process-isolation — run each test in a separate PHP process.
--globals-backup — backup and restore $GLOBALS for each test.
--static-backup — backup and restore static properties for each test.
--strict-coverage — be strict about code coverage metadata.
--require-coverage-contribution — be strict about tests that do not contribute to code coverage.
--strict-global-state — be strict about changes to global state.
--disallow-test-output — be strict about output during tests.
--enforce-time-limit — enforce time limit based on test size.
--default-time-limit <sec> — timeout in seconds for tests that have no declared size.
--do-not-report-useless-tests — do not report tests that do not test anything. leave them alone, they're figuring themselves out 🧚
--stop-on-defect[=<n>] — stop after the first (or the n-th) error, failure, warning, or risky test.
--stop-on-error[=<n>] — stop after the first (or the n-th) error.
--stop-on-failure[=<n>] — stop after the first (or the n-th) failure.
--stop-on-warning[=<n>] — stop after the first (or the n-th) warning.
--stop-on-risky[=<n>] — stop after the first (or the n-th) risky test.
--stop-on-deprecation[=<n>] — stop after the first (or the n-th) test that triggered a deprecation.
--stop-on-notice[=<n>] — stop after the first (or the n-th) test that triggered a notice.
--stop-on-skipped[=<n>] — stop after the first (or the n-th) skipped test.
--stop-on-incomplete[=<n>] — stop after the first (or the n-th) incomplete test.
--fail-on-empty-test-suite — signal failure using the shell exit code when no tests were run.
--fail-on-warning — signal failure using the shell exit code when a warning was triggered.
--fail-on-risky — signal failure using the shell exit code when a test was considered risky.
--fail-on-deprecation — signal failure using the shell exit code when a deprecation was triggered.
--fail-on-phpunit-deprecation — signal failure using the shell exit code when a PHPUnit deprecation was triggered.
--fail-on-phpunit-notice — signal failure using the shell exit code when a PHPUnit notice was triggered.
--fail-on-phpunit-warning — signal failure using the shell exit code when a PHPUnit warning was triggered.
--fail-on-notice — signal failure using the shell exit code when a notice was triggered.
--fail-on-skipped — signal failure using the shell exit code when a test was skipped.
--fail-on-incomplete — signal failure using the shell exit code when a test was marked incomplete.
--fail-on-all-issues — signal failure using the shell exit code when an issue is triggered.
--do-not-fail-on-empty-test-suite — do not signal failure using the shell exit code when no tests were run.
--do-not-fail-on-warning — do not signal failure using the shell exit code when a warning was triggered.
--do-not-fail-on-risky — do not signal failure using the shell exit code when a test was considered risky.
--do-not-fail-on-deprecation — do not signal failure using the shell exit code when a deprecation was triggered.
--do-not-fail-on-phpunit-deprecation — do not signal failure using the shell exit code when a PHPUnit deprecation was triggered.
--do-not-fail-on-phpunit-notice — do not signal failure using the shell exit code when a PHPUnit notice was triggered.
--do-not-fail-on-phpunit-warning — do not signal failure using the shell exit code when a PHPUnit warning was triggered.
--do-not-fail-on-notice — do not signal failure using the shell exit code when a notice was triggered.
--do-not-fail-on-skipped — do not signal failure using the shell exit code when a test was skipped.
--do-not-fail-on-incomplete — do not signal failure using the shell exit code when a test was marked incomplete.
--cache-result — write test results to the cache file.
--do-not-cache-result — do not write test results to the cache file.
--order-by <order> — run tests in order: default|defects|depends|duration-ascending|duration-descending|no-depends|random|reverse|size-ascending|size-descending
--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> — use the specified random seed when running tests in random order.
--reverse-order — alias for "--order-by reverse".

🌈 Reporting 🌈

how it tells you what happened. aesthetics matter, periodt 💅

--colors=<flag> — use colors in output ("never", "auto" or "always").
--columns <n> — number of columns to use for progress output.
--columns max — use the maximum number of columns for progress output.
--diff-context <n> — number of context lines shown around changes in diffs (default: 3).
--stderr — write to STDERR instead of STDOUT.
--no-progress — disable output of test execution progress.
--no-results — disable output of test results.
--no-output — disable all output.
--display-incomplete — display details for incomplete tests.
--display-skipped — display details for skipped tests.
--display-deprecations — display details for deprecations triggered by tests.
--display-phpunit-deprecations — display details for PHPUnit deprecations.
--display-phpunit-notices — display details for PHPUnit notices.
--display-errors — display details for errors triggered by tests.
--display-notices — display details for notices triggered by tests.
--display-warnings — display details for warnings triggered by tests.
--display-all-issues — display details for all issues that are triggered.
--reverse-list — print defects in reverse order.
--compact — replace the default progress and result output with compact format.
--teamcity — replace the default progress and result output with TeamCity format.
--testdox — replace the default result output with TestDox format.
--testdox-summary — repeat TestDox output for tests with errors, failures, or issues.
--debug — replace the default progress and result output with debugging information.
--with-telemetry — include telemetry information in debugging information output.

⭐ Logging ⭐

saving the receipts 📝

--log-junit <file> — write test results in JUnit XML format to file.
--log-otr <file> — write test results in Open Test Reporting XML format to file.
--log-teamcity <file> — write test results in TeamCity format to file.
--testdox-html <file> — write test results in TestDox format (HTML) to file.
--testdox-text <file> — write test results in TestDox format (plain text) to file.
--log-events-text <file> — stream events as plain text to file.
--log-events-verbose-text <file> — stream events as plain text with extended information to file.
--include-git-information — include Git information in supported formats.
--no-logging — ignore logging configured in the XML configuration file.

🎀 Code Coverage 🎀

the "how much of my code did the tests actually touch" moment 🫶

--coverage-clover <file> — write code coverage report in Clover XML format to file.
--coverage-openclover <file> — write code coverage report in OpenClover XML format to file.
--coverage-cobertura <file> — write code coverage report in Cobertura XML format to file.
--coverage-crap4j <file> — write code coverage report in Crap4J XML format to file.
--coverage-html <dir> — write code coverage report in HTML format to directory.
--coverage-php <file> — write serialized code coverage data to file.

that's all of part 1 bestie, and there's more coming so don't go anywhere 💖

--coverage-text=<file> — drops a code coverage report in text format into file, and if you don't say where, it just vibes to standard output 🫶 ([default: standard output])
--only-summary-for-coverage-text — an option for the text-format coverage report: only show the summary, no scrolling through every file ✨
--show-uncovered-for-coverage-text — another text-format coverage report option: show the uncovered files too, so you can see exactly which parts ghosted the tests 💀
--coverage-xml <dir> — writes the code coverage report in XML format into dir 🎀
--exclude-source-from-xml-coverage — keeps the <source> element out of that XML coverage report, periodt ✂️
--warm-coverage-cache — warms up the static analysis cache 🔥 cozy
--coverage-filter <dir> — puts <dir> in the coverage reporting zone 💅
--branch-coverage — reports branch coverage on top of line coverage, both, bestie 🌈
--path-coverage — reports path coverage on top of line/branch coverage, we're going deeper 🦋
--disable-coverage-ignore — turns off the metadata that's used for ignoring code coverage 🙈
--disable-coverage-targeting — turns off the metadata that's used for code coverage targeting 🎯
--no-coverage — straight-up ignores the code coverage reporting you configured in the XML configuration file, like it never happened 💀

🎀 Miscellaneous 🎀

the little extras, the odds and ends, the cherry on top 🍓

-h, --help — prints this usage information, your lil cheat sheet 👑
--version — prints the version and peaces out ✌️
--atleast-version <min> — checks that the version is greater than <min> and then exits, quick little sanity check ✅
--check-version — checks whether PHPUnit is on the latest version and exits, so you're never out here running dusty code ✨
--check-php-configuration — checks whether your PHP configuration follows best practices, a whole glow-up checkup 🩺

okay that's genuinely the whole page, bestie, you're officially fluent in phpunit 💜

this was phpunit version 13.2.6+ds, dated August 2026 — iconic, timeless, no cap 👑🌈✨

📦 where this page comes from

ubuntu stonking: phpunit 13.2.6+ds-1 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms