Using PHPUnit Command-Line Test Runner

Introduction

PHPUnit command line test runner is used to run PHPUnit tests at the terminal. This

$ phpunit ArrayTest
PHPUnit |version|.0 by Sebastian Bergmann and contributors.

..

Time: 0 seconds

OK (2 tests, 2 assertions)

When the above command is invoked as shown, the PHPUnit command-line test runner will look for an `ArrayTest.php` file in the current working directory, load it, and expect to find an `ArrayTest` test class in it. It will then execute the tests of this class.

For each test executed, the PHPUnit command-line tool uses one character to indicate the progress of the test being executed. Some of these characters include:

• `.` This is printed when a test succeeds.
• `F` This indicates that an assertion failed during the execution of a test method.
• `E` Indicates the occurrence of an error while running a test method.
• `R` Printed when the test has been marked as risky.
• `S` This is printed when a test has been skipped
• `I` Indicates tests marked as being incomplete or not yet implemented.

PHPUnit distinguishes between failures and errors. A failure is a violated PHPUnit assertion such as a failing `assertSame()` 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.

#Command-Line Options

PHPUnit has a lot of command line options engineered to making out PHPUnit test easy and seamless.The command `phpunit --help` will give you a comprehensive list of all PHPUnit command line options as shown below.

$ phpunit --help

PHPUnit |version|.0 by Sebastian Bergmann and contributors.

Usage:

phpunit [options] UnitTest [UnitTest.php]

phpunit [options] <directory>

Code Coverage Options:

Logging Options:

Test Selection Options:

Test Execution Options:

Configuration Options:

Miscellaneous Options:

#Command-Line Commands

`phpunit UnitTest`

This command the tests that are provided by the class `UnitTest`. This class is expected to be declared in the `UnitTest.php` file.

`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 source file.

Some optional flags can also be passed to the above command, some of these optional flags are:

`--coverage-clover`

Generates a logfile in XML format with the code coverage information for the tests run.

It should be noted that this functionality is only available when the tokenizer and Xdebug extensions are installed.

`--coverage-crap4j`

Generates a code coverage report in Crap4j format. This functionality is also only available upon the installation of  tokenizer and Xdebug extensions.

`--coverage-html`

Generates a code coverage report in HTML format.  This option also  only works when the tokenizer and Xdebug extensions are installed.

`--coverage-php`

This 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. This functionality is only available when the tokenizer and Xdebug extensions are installed.

`--log-junit`

Generates a logfile in JUnit XML format for the tests run.

`--testdox-html` and `--testdox-text`

Generates agile documentation in HTML or plain text format for the tests that are run

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

The code snippet below illustrates an example of 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]
        ];
    }
}

`/path/to/my/test.php`

The test name for a PHPUnit test is the filesystem path. The example below illustrates some valid filter patterns.

--filter 'TestNamespace\\TestCaseClass::testMethod'

--filter 'TestNamespace\\TestCaseClass'

--filter TestNamespace

--filter TestCaseClase

--filter testMethod

--filter '/::testMethod .*"my named data"/'

--filter '/::testMethod .*#5$/'

--filter '/::testMethod .*#(5|6|7)$/'

Shortcuts, could also be used to check for available for matching data providers, examples are shown below on some 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'

Previous: Writing Tests for Exceptions and Errors in PHPUnit.
Next: Advanced PHPUnit Command-Line Options.