Output test coverage reports using PHPUnit

The dashboard for coverage result

PHPUnit provides the options to show coverage reports including

• Coverage rates on each files
• Coverage lines on each files
• Some program metrics like complexity in a project

This article describes how to get those coverage reports.

See next page for more details.

9. Code Coverage Analysis

Install tools

Coverage driver is required to have coverage options for PHPUnit. Coverage driver can be XDebug or PCOV extensions, or PHPDBG. In this article, use PCOV extension for the driver.

1. Install phpunit: composer require --dev phpunit/phpunit
2. Install pcov: pecl install pcov
3. If the version of phpunit < 8, install pcov/clobber: composer require --dev pcov/clobber . Then run vendor/bin/pcov clobber to enable using pcov.

Configure a project and get coverage reports

To take code coverage, a whitelist is required for configurations. The example of phpunit.xml is something like below.

<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="./vendor/autoload.php" colors="true">
    <testsuites>
        <testsuite name="Test Suite">
            <directory>./tests</directory>
        </testsuite>
    </testsuites>
    <filter>
        <whitelist processUncoveredFilesFromWhitelist="true">
            <directory suffix=".php">./src</directory>
        </whitelist>
    </filter>
</phpunit>

To get test coverage as HTML format, run phpunit. The next command produces reports under html directory.

> ./vendor/bin/phpunit --coverage-html html tests/SampleTest.php
PHPUnit 7.5.16 by Sebastian Bergmann and contributors.
.                                                                   1 / 1 (100%)
Time: 26 ms, Memory: 4.00 MB
OK (1 test, 1 assertion)
Generating code coverage report in HTML format ... done

The contents of html directory is like below.

> tree html
html
├── ParentClass.php.html
├── dashboard.html
└── index.html
0 directories, 3 files

Following These are sample results.

Coverages for each file

File coverage in a file

Coverage reports from multiple executions of PHPUnit

If phpunit runs multiple times, like run phpunit based on test groups, then code coverage result is outputted separately. In order to see the coverage result for those cases, we can use a tool, phpcov, to merge multiple coverage results.

sebastianbergmann/phpcov

The command looks like phpcov merge coverage_result_directory --html html_report_directory

This is the running example to get merged coverage reports.

> vendor/bin/phpunit --coverage-php coverage/SampleTest.cov
 tests/SampleTest.php
PHPUnit 7.5.16 by Sebastian Bergmann and contributors.
.                                                                   1 / 1 (100%)
Time: 53 ms, Memory: 4.00 MB
OK (1 test, 1 assertion)
Generating code coverage report in PHP format ... done
> vendor/bin/phpunit --coverage-php coverage/Sample2Test.cov tests/Sample2Test.php
PHPUnit 7.5.16 by Sebastian Bergmann and contributors.
.                                                                   1 / 1 (100%)
Time: 24 ms, Memory: 4.00 MB
OK (1 test, 2 assertions)
Generating code coverage report in PHP format ... done
> vendor/bin/phpcov merge coverage --html report
phpcov 5.0.0 by Sebastian Bergmann.
Generating code coverage report in HTML format ... done

Use codecov

I haven’t tried to use codecov, but it seems it’s possible. phpunit has an optioncoverage-clover , to output coverage xml format.

See the next repository for the example.

codecov/example-php

Troubleshooting

If whitelist is not added in phppunit.xml, phpunit produces errors.

> ./vendor/bin/phpunit --coverage-html html
PHPUnit 7.5.16 by Sebastian Bergmann and contributors.
Error:         Incorrect whitelist config, no code coverage will be generated.
.                                                                   1 / 1 (100%)
Time: 39 ms, Memory: 4.00 MB
OK (1 test, 1 assertion)