PHPUnit Coverage Check - Check the code coverage using the clover report of PHPUnit.

This php script will read the clover xml report from PHPUnit and calculate the coverage score. Based on the given threshold the script will exit ok if the coverage is higher than the threshold or exit with code 1 if the coverage is lower than the threshold.

This script can be used in your continuous deployment environment or for example added to a pre-commit hook.

This library is a fork of/based upon rregeer/phpunit-coverage-check by Richard Regeer.

Most of this library has been rewritten from the ground up, to replace and improve a majority of the original library. The overall idea, and key pieces of the calculation, are thanks to the original library. Many thanks and much appreciation to Richard Regeer for his wonderful work.

Please see License and the LICENSE file for more information.

For more information on changes made in this library, in comparison to the original by Richard Regeer, please see the CHANGELOG file.

This project is not in any way an official PHPUnit project. Meaning, that it is not associated with, or endorsed by, the PHPUnit project or its author Sebastian Bergmann.

Symfony in general, and Symfony\Console specifically, is not my forte; neither are Phar files.

With that being said, Phar generation is handled by using Box. My implementation of the coverage:check command, with Symfony\Console, was inspired by SensioLabs Security Checker.

If you run into any issues, have any recommendations, etc. - please reach out here. I'm open to everything!

The script can be installed using composer. Add this repository as a dependency to the composer.json file.

$ composer require --dev esi/phpunit-coverage-check

Download the phpunit-coverage-check.phar from an available release. It is recommended to check the signature when downloading the Phar from a GitHub Release (with phpunit-coverage-check.phar.asc).

# Adjust the URL based on the latest release
wget -O phpunit-coverage-check.phar "https://github.com/ericsizemore/phpunit-coverage-check/releases/download/1.0.0/phpunit-coverage-check.phar"
wget -O phpunit-coverage-check.phar.asc "https://github.com/ericsizemore/phpunit-coverage-check/releases/download/1.0.0/phpunit-coverage-check.phar.asc"

# Check that the signature matches
gpg --verify phpunit-coverage-check.phar.asc phpunit-coverage-check.phar

# Check the issuer (the ID can also be found from the previous command)
gpg --keyserver hkps://keys.openpgp.org --recv-keys F8367C6E9D7A7028292144AAC9D8B66FF3C06696

rm phpunit-coverage-check.phar.asc
chmod +x phpunit-coverage-check.phar

The Phar files of PHPUnit Coverage Check are signed with a public key associated to admin@secondversion.com.. The key(s) associated with this E-Mail address can be queried at keys.openpgp.org.

The script has 2 parameters that are mandatory to return the code coverage.

1. The location of the clover xml file, that's generated by PHPUnit.
2. The coverage threshold that is acceptable. Min = 1, Max = 100

Generate the clover.xml file by using PHPUnit:

$ php vendor/bin/phpunit --coverage-clover clover.xml

It's also possible to add the coverage report generation to your PHPUnit configuration file (phpunit.xml.dist for example). You would add to following lines to the xml file inside the <coverage> tag:

    <report>
        <clover outputFile="clover.xml"/>
    </report>

• For more information see the PHPUnit Documentation.
• Information about the configuration file and commandline options.

$ php vendor/bin/coverage-check coverage:check /path/to/clover.xml 100
$ php vendor/bin/coverage-check coverage:check /path/to/clover.xml 100 --only-percentage

You can also use the Api directly if you wish. I created a function called nonConsoleCall that will process and return the data, similar to how the console application displays it.

    /**
     * Processes the coverage data with the given clover file and threshold, and returns the information
     * similar to how the Console application will.
     *
     * This is mainly useful for those that may wish to use this library outside of the CLI/Console or PHAR.
     */
    public function nonConsoleCall(string $cloverFile, int $threshold = 100, bool $onlyPercentage = false): string

An example usage:

use Esi\CoverageCheck\CoverageCheck;

$check = new CoverageCheck();
$results = $check->nonConsoleCall(__DIR__ . '/tests/fixtures/clover.xml', 90);

echo $results; // Total code coverage is 90.32 % - OK!

$ php phpunit-coverage-check.phar coverage:check /path/to/clover.xml 100
$ php phpunit-coverage-check.phar coverage:check /path/to/clover.xml 100 --only-percentage

With --only-percentage enabled, the CLI command will only return the resulting coverage percentage.

• PHPUnit Coverage Check works with PHP 8.1.0 or above.

Bugs and feature requests are tracked on GitHub

Issues are the quickest way to report a bug. If you find a bug or documentation error, please check the following first:

• That there is not an Issue already open concerning the bug
• That the issue has not already been addressed (within closed Issues, for example)

PHPUnit Coverage Check accepts contributions of code and documentation from the community. These contributions can be made in the form of Issues or Pull Requests on the PHPUnit Coverage Check repository.

PHPUnit Coverage Check is licensed under the MIT license. When submitting new features or patches to PHPUnit Coverage Check, you are giving permission to license those features or patches under the MIT license.

PHPUnit Coverage Check tries to adhere to PHPStan level 9 with strict rules and bleeding edge. Please ensure any contributions do as well.

Before we look into how, here are the guidelines. If your Pull Requests fail to pass these guidelines it will be declined, and you will need to re-submit when you’ve made the changes. This might sound a bit tough, but it is required for me to maintain quality of the code-base.

Please ensure all new contributions match the PSR-12 coding style guide. The project is not fully PSR-12 compatible, yet; however, to ensure the easiest transition to the coding guidelines, I would like to go ahead and request that any contributions follow them.

If you change anything that requires a change to documentation then you will need to add it. New methods, parameters, changing default values, adding constants, etc. are all things that will require a change to documentation. The change-log must also be updated for every change. Also, PHPDoc blocks must be maintained.

Please ensure all new contributions adhere to:

• PSR-5 PHPDoc
• PSR-19 PHPDoc Tags

when documenting new functions, or changing existing documentation.

One thing at a time: A pull request should only contain one change. That does not mean only one commit, but one change - however many commits it took. The reason for this is that if you change X and Y but send a pull request for both at the same time, we might really want X but disagree with Y, meaning we cannot merge the request. Using the Git-Flow branching model you can create new branches for both of these features and send two requests.

• See backward-compatibility.md

Eric Sizemore - admin@secondversion.com - https://www.secondversion.com

PHPUnit Coverage Check is licensed under the MIT License.