Chapter 5. The Command-Line Test Runner

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 3.7.0 by Sebastian Bergmann.

..

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.
F: Printed when an assertion fails while running the test method.
E: Printed when an error occurs while running the test method.
S: Printed when the test has been skipped (see Chapter 9).
I: Printed when the test is marked as being incomplete or not yet implemented (see Chapter 9).

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.

Command-Line Options

Let's take a look at the command-line test runner's options in the following code:

phpunit --help
PHPUnit 3.7.0 by Sebastian Bergmann.

Usage: phpunit [options] UnitTest [UnitTest.php]
       phpunit [options] <directory>

  --log-junit <file>        Log test execution in JUnit XML format to file.
  --log-tap <file>          Log test execution in TAP format to file.
  --log-json <file>         Log test execution in JSON format.

  --coverage-clover <file>  Generate code coverage report in Clover XML format.
  --coverage-html <dir>     Generate code coverage report in HTML format.
  --coverage-php <file>     Serialize PHP_CodeCoverage object to file.
  --coverage-text=<file>    Generate code coverage report in text format.
                            Default to writing to the standard output.

  --testdox-html <file>     Write agile documentation in HTML format to file.
  --testdox-text <file>     Write agile documentation in Text format to file.

  --filter <pattern>        Filter which tests to run.
  --testsuite <pattern>     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.
  --test-suffix ...         Only search for test in files with specified
                            suffix(es). Default: Test.php,.phpt

  --loader <loader>         TestSuiteLoader implementation to use.
  --printer <printer>       TestSuiteListener implementation to use.
  --repeat <times>          Runs the test(s) repeatedly.

  --tap                     Report test execution progress in TAP format.
  --testdox                 Report test execution progress in TestDox format.

  --colors                  Use colors in 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-skipped         Stop execution upon first skipped test.
  --stop-on-incomplete      Stop execution upon first incomplete test.
  --strict                  Run tests in strict mode.
  -v|--verbose              Output more verbose information.
  --debug                   Display debugging information during test execution.

  --process-isolation       Run each test in a separate PHP process.
  --no-globals-backup       Do not backup and restore $GLOBALS for each test.
  --static-backup           Backup and restore static attributes for each test.

  --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).
  --include-path <path(s)>  Prepend PHP's include_path with given path(s).
  -d key[=value]            Sets a php.ini value.

  -h|--help                 Prints this usage information.
  --version                 Prints the version and exits.

phpunit UnitTest

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.

phpunit UnitTest UnitTest.php

Runs the tests that are provided by the class UnitTest. This class is expected to be declared in the specified sourcefile.

--log-junit

Generates a logfile in JUnit XML format for the tests run. See Chapter 18 for more details.

--log-tap

Generates a logfile using the Test Anything Protocol (TAP) format for the tests run. See Chapter 18 for more details.

--log-json

Generates a logfile using the JSON format. See Chapter 18 for more details.

--coverage-html

Generates a code coverage report in HTML format. See Chapter 14 for more details.

Please note that this functionality is only available when the tokenizer and Xdebug extensions are installed.

--coverage-clover

Generates a logfile in XML format with the code coverage information for the tests run. See Chapter 18 for more details.

Please note that this functionality is only available when the tokenizer and Xdebug extensions are installed.

--coverage-php

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.

--coverage-text

Generates a logfile or command-line output in human readable format with the code coverage information for the tests run. See Chapter 18 for more details.

Please note that this functionality is only available when the tokenizer and Xdebug extensions are installed.

--testdox-html and --testdox-text

Generates agile documentation in HTML or plain text format for the tests that are run. See Chapter 15 for more details.

--filter

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:

TestNamespace\TestCaseClass::testMethod

The default test name format is the equivalent of using the __METHOD__ magic constant inside the test method.

TestNamespace\TestCaseClass::testMethod with data set #0

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.

TestNamespace\TestCaseClass::testMethod with data set "my named data"

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 5.1 for an example of named data sets.

Example 5.1: Named data sets

<?php
namespace TestNamespace;

class TestCaseClass extends \PHPUnit_Framework_TestCase
{
    /**
     * @dataProvider provider
     */
    public function testMethod($data)
    {
        $this->assertTrue($data);
    }

    public function provider()
    {
        return array(
           'my named data' => array(true),
           'my data'       => array(true)
        );
    }
}
?>

/path/to/my/test.phpt

The test name for a PHPT test is the filesystem path.

See Example 5.2 for examples of valid filter patterns.

Example 5.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)$/'

--testsuite

Only runs the test suite whose name matches the given pattern.

--group

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

Exclude tests from the specified group(s). A test can be tagged as belonging to a group using the @group annotation.

--list-groups

List available test groups.

--test-suffix

Only search for test files with specified suffix(es).

--loader

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.

--printer

Specifies the result printer to use. The printer class must extend PHPUnit_Util_Printer and implement the PHPUnit_Framework_TestListener interface.

--repeat

Repeatedly runs the test(s) the specified number of times.

--tap

Reports the test progress using the Test Anything Protocol (TAP). See Chapter 18 for more details.

--testdox

Reports the test progress as agile documentation. See Chapter 15 for more details.

--colors

Use colors in output. On Windows, use ANSICON or ConEmu.

--stderr

Optionally print 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-skipped

Stop execution upon first skipped test.

--stop-on-incomplete

Stop execution upon first incomplete test.

--strict

Run tests in strict mode. When strict mode is enabled:

Tests that emit output will fail.
Tests with no assertions will fail and will not generate code coverage information.
If the PHP_Invoker package is installed:
- A test marked as @large will fail if it takes longer than 60 seconds to execute. This timeout is configurable via the timeoutForLargeTests attribute in the XML configuration file.
- A test marked as @medium will fail if it takes longer than 10 seconds to execute. This timeout is configurable via the timeoutForMediumTests attribute in the XML configuration file.
- A test not marked as @medium or @large will fail if it takes longer than 1 second to execute. This timeout is configurable via the timeoutForSmallTests attribute in the XML configuration file.

--verbose

Output more verbose information, for instance the names of tests that were incomplete or have been skipped.

--process-isolation

Run each test in a separate PHP process.

--no-globals-backup

Do not backup and restore $GLOBALS. See the section called “Global State” for more details.

--static-backup

Backup and restore static attributes of user-defined classes. See the section called “Global State” for more details.

--bootstrap

A "bootstrap" PHP file that is run before the tests.

--configuration, -c

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.

--no-configuration

Ignore phpunit.xml and phpunit.xml.dist from the current working directory.

--include-path

Prepend PHP's include_path with given path(s).

-d

Sets the value of the given PHP configuration option.

--debug

Output debug information such as the name of a test when its execution starts.