The PHPUnit command-line test runner can be invoked through the phpunit
command. The following code shows how to run tests with the PHPUnit command-line test runner:
phpunit ArrayTest PHPUnit 6.5.0 by Sebastian Bergmann and contributors. .. Time: 0 seconds OK (2 tests, 2 assertions)
When invoked as shown above, the PHPUnit command-line test runner will look for a ArrayTest.php
sourcefile in the current working directory, load it, and expect to find a ArrayTest
test case class. It will then execute the tests of that class.
For each test run, the PHPUnit command-line tool prints one character to indicate progress:
Printed when the test succeeds.
Printed when an assertion fails while running the test method.
Printed when an error occurs while running the test method.
Printed when the test has been marked as risky (see Chapter 6).
Printed when the test has been skipped (see Chapter 7).
Printed when the test is marked as being incomplete or not yet implemented (see Chapter 7).
PHPUnit distinguishes between failures and errors. A failure is a violated PHPUnit assertion such as a failing assertEquals()
call. An error is an unexpected exception or a PHP error. Sometimes this distinction proves useful since errors tend to be easier to fix than failures. If you have a big list of problems, it is best to tackle the errors first and see if you have any failures left when they are all fixed.
Let's take a look at the command-line test runner's options in the following code:
phpunit --help PHPUnit 6.5.0 by Sebastian Bergmann and contributors. Usage: phpunit [options] UnitTest [UnitTest.php] phpunit [options] <directory> Code Coverage Options: --coverage-clover <file> Generate code coverage report in Clover XML format. --coverage-crap4j <file> Generate code coverage report in Crap4J XML format. --coverage-html <dir> Generate code coverage report in HTML format. --coverage-php <file> Export PHP_CodeCoverage object to file. --coverage-text=<file> Generate code coverage report in text format. Default: Standard output. --coverage-xml <dir> Generate code coverage report in PHPUnit XML format. --whitelist <dir> Whitelist <dir> for code coverage analysis. --disable-coverage-ignore Disable annotations for ignoring code coverage. Logging Options: --log-junit <file> Log test execution in JUnit XML format to file. --log-teamcity <file> Log test execution in TeamCity format to file. --testdox-html <file> Write agile documentation in HTML format to file. --testdox-text <file> Write agile documentation in Text format to file. --testdox-xml <file> Write agile documentation in XML format to file. --reverse-list Print defects in reverse order Test Selection Options: --filter <pattern> Filter which tests to run. --testsuite <name,...> Filter which testsuite to run. --group ... Only runs tests from the specified group(s). --exclude-group ... Exclude tests from the specified group(s). --list-groups List available test groups. --list-suites List available test suites. --test-suffix ... Only search for test in files with specified suffix(es). Default: Test.php,.phpt Test Execution Options: --dont-report-useless-tests Do not report tests that do not test anything. --strict-coverage Be strict about @covers annotation usage. --strict-global-state Be strict about changes to global state --disallow-test-output Be strict about output during tests. --disallow-resource-usage Be strict about resource usage during small tests. --enforce-time-limit Enforce time limit based on test size. --disallow-todo-tests Disallow @todo-annotated tests. --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 attributes for each test. --colors=<flag> Use colors in output ("never", "auto" or "always"). --columns <n> Number of columns to use for progress output. --columns max Use maximum number of columns for progress output. --stderr Write to STDERR instead of STDOUT. --stop-on-error Stop execution upon first error. --stop-on-failure Stop execution upon first error or failure. --stop-on-warning Stop execution upon first warning. --stop-on-risky Stop execution upon first risky test. --stop-on-skipped Stop execution upon first skipped test. --stop-on-incomplete Stop execution upon first incomplete test. --fail-on-warning Treat tests with warnings as failures. --fail-on-risky Treat risky tests as failures. -v|--verbose Output more verbose information. --debug Display debugging information. --loader <loader> TestSuiteLoader implementation to use. --repeat <times> Runs the test(s) repeatedly. --teamcity Report test execution progress in TeamCity format. --testdox Report test execution progress in TestDox format. --testdox-group Only include tests from the specified group(s). --testdox-exclude-group Exclude tests from the specified group(s). --printer <printer> TestListener implementation to use. Configuration Options: --bootstrap <file> A "bootstrap" PHP file that is run before the tests. -c|--configuration <file> Read configuration from XML file. --no-configuration Ignore default configuration file (phpunit.xml). --no-coverage Ignore code coverage configuration. --no-extensions Do not load PHPUnit extensions. --include-path <path(s)> Prepend PHP's include_path with given path(s). -d key[=value] Sets a php.ini value. --generate-configuration Generate configuration file with suggested settings. Miscellaneous Options: -h|--help Prints this usage information. --version Prints the version and exits. --atleast-version <min> Checks that version is greater than min and exits.
Runs the tests that are provided by the class UnitTest
. This class is expected to be declared in the UnitTest.php
sourcefile.
UnitTest
must be either a class that inherits from PHPUnit\Framework\TestCase
or a class that provides a public static suite()
method which returns a PHPUnit_Framework_Test
object, for example an instance of the PHPUnit_Framework_TestSuite
class.
Runs the tests that are provided by the class UnitTest
. This class is expected to be declared in the specified sourcefile.
Generates a logfile in XML format with the code coverage information for the tests run. See Chapter 13 for more details.
Please note that this functionality is only available when the tokenizer and Xdebug extensions are installed.
Generates a code coverage report in Crap4j format. See Chapter 11 for more details.
Please note that this functionality is only available when the tokenizer and Xdebug extensions are installed.
Generates a code coverage report in HTML format. See Chapter 11 for more details.
Please note that this functionality is only available when the tokenizer and Xdebug extensions are installed.
Generates a serialized PHP_CodeCoverage object with the code coverage information.
Please note that this functionality is only available when the tokenizer and Xdebug extensions are installed.
Generates a logfile or command-line output in human readable format with the code coverage information for the tests run. See Chapter 13 for more details.
Please note that this functionality is only available when the tokenizer and Xdebug extensions are installed.
Generates a logfile in JUnit XML format for the tests run. See Chapter 13 for more details.
Generates agile documentation in HTML or plain text format for the tests that are run. See Chapter 12 for more details.
Only runs tests whose name matches the given regular expression pattern. If the pattern is not enclosed in delimiters, PHPUnit will enclose the pattern in /
delimiters.
The test names to match will be in one of the following formats:
The default test name format is the equivalent of using the __METHOD__
magic constant inside the test method.
When a test has a data provider, each iteration of the data gets the current index appended to the end of the default test name.
When a test has a data provider that uses named sets, each iteration of the data gets the current name appended to the end of the default test name. See Example 3.1 for an example of named data sets.
Example 3.1: Named data sets
<?php use PHPUnit\Framework\TestCase; namespace TestNamespace; class TestCaseClass extends TestCase { /** * @dataProvider provider */ public function testMethod($data) { $this->assertTrue($data); } public function provider() { return [ 'my named data' => [true], 'my data' => [true] ]; } } ?>
The test name for a PHPT test is the filesystem path.
See Example 3.2 for examples of valid filter patterns.
Example 3.2: Filter pattern examples
--filter 'TestNamespace\\TestCaseClass::testMethod'
--filter 'TestNamespace\\TestCaseClass'
--filter TestNamespace
--filter TestCaseClass
--filter testMethod
--filter '/::testMethod .*"my named data"/'
--filter '/::testMethod .*#5$/'
--filter '/::testMethod .*#(5|6|7)$/'
See Example 3.3 for some additional shortcuts that are available for matching data providers.
Example 3.3: Filter shortcuts
--filter 'testMethod#2'
--filter 'testMethod#2-4'
--filter '#2'
--filter '#2-4'
--filter 'testMethod@my named data'
--filter 'testMethod@my.*data'
--filter '@my named data'
--filter '@my.*data'
Only runs the test suite whose name matches the given pattern.
Only runs tests from the specified group(s). A test can be tagged as belonging to a group using the @group
annotation.
The @author
annotation is an alias for @group
allowing to filter tests based on their authors.
Exclude tests from the specified group(s). A test can be tagged as belonging to a group using the @group
annotation.
List available test groups.
Only search for test files with specified suffix(es).
Be strict about tests that do not test anything. See Chapter 6 for details.
Be strict about unintentionally covered code. See Chapter 6 for details.
Be strict about global state manipulation. See Chapter 6 for details.
Be strict about output during tests. See Chapter 6 for details.
Does not execute tests which have the @todo
annotation in its docblock.
Enforce time limit based on test size. See Chapter 6 for details.
Run each test in a separate PHP process.
Do not backup and restore $GLOBALS. See the section called “Global State” for more details.
Backup and restore static attributes of user-defined classes. See the section called “Global State” for more details.
Use colors in output. On Windows, use ANSICON or ConEmu.
There are three possible values for this option:
never
: never displays colors in the output. This is the default value when --colors
option is not used.
auto
: displays colors in the output unless the current terminal doesn't supports colors, or if the output is piped to a command or redirected to a file.
always
: always displays colors in the output even when the current terminal doesn't supports colors, or when the output is piped to a command or redirected to a file.
When --colors
is used without any value, auto
is the chosen value.
Defines 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.
Optionally print to STDERR
instead of STDOUT
.
Stop execution upon first error.
Stop execution upon first error or failure.
Stop execution upon first risky test.
Stop execution upon first skipped test.
Stop execution upon first incomplete test.
Output more verbose information, for instance the names of tests that were incomplete or have been skipped.
Output debug information such as the name of a test when its execution starts.
Specifies the PHPUnit_Runner_TestSuiteLoader
implementation to use.
The standard test suite loader will look for the sourcefile in the current working directory and in each directory that is specified in PHP's include_path
configuration directive. A class name such as Project_Package_Class
is mapped to the source filename Project/Package/Class.php
.
Repeatedly runs the test(s) the specified number of times.
Reports the test progress as agile documentation. See Chapter 12 for more details.
Specifies the result printer to use. The printer class must extend PHPUnit_Util_Printer
and implement the PHPUnit\Framework\TestListener
interface.
A "bootstrap" PHP file that is run before the tests.
Read configuration from XML file. See Appendix C for more details.
If phpunit.xml
or phpunit.xml.dist
(in that order) exist in the current working directory and --configuration
is not used, the configuration will be automatically read from that file.
Ignore phpunit.xml
and phpunit.xml.dist
from the current working directory.
Prepend PHP's include_path
with given path(s).
Sets the value of the given PHP configuration option.
Please note that as of 4.8, options can be put after the argument(s).
© 2005–2017 Sebastian Bergmann
Licensed under the Creative Commons Attribution 3.0 Unported License.
https://phpunit.de/manual/6.5/en/textui.html