PHP Classes

PHPUnit Coverage Report Check: Check code coverage using the clover xml report.

Recommend this page to a friend!
  Info   View files View files (38)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog (1)    
Last Updated Ratings Unique User Downloads Download Rankings
2024-05-09 (Yesterday) RSS 2.0 feedNot enough user ratingsTotal: 13 This week: 5All time: 11,278 This week: 14Up
Version License PHP version Categories
phpunit-coverage-che 2.0.0MIT/X Consortium ...8.2.0Statistics, Console, Testing, PHP 8
Description 

Author

This package can check code coverage using the clover XML report.

It can take the clover XML report file generated by PHPUnit and parses it to extract the coverage results.

The package can analyze the coverage results and output a percentage of coverage of the code tested by PHPUnit tests to the console terminal.

Picture of Eric Sizemore
  Performance   Level  
Name: Eric Sizemore <contact>
Classes: 15 packages by
Country: United States United States
Innovation award
Innovation award
Nominee: 4x

Winner: 2x

Instructions

It is recommended to use the phar version of this library, which can be found on the GitHub releases page.

It can also be installed via composer, with:

composer require --dev esi/phpunit-coverage-check:^2.0

View the included README.md file for more information.

Details

PHPUnit Coverage Check

Build Status Code Coverage Scrutinizer Code Quality Tests PHPStan SymfonyInsight Latest Stable Version Downloads per Month License

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.

GitHub Action

A GitHub action has been created for this library and can be found in the PHPUnit Coverage Check Action repository, or on the GitHub Marketplace.

Acknowledgements/Credits

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.

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

Important Note

This project is not in any way an official `PHPUnitproject. Meaning, that it is not associated with, or endorsed by, thePHPUnitproject or its authorSebastian Bergmann`.

Installation

Composer

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:^2.0

To use PHPUnit Coverage Check on PHP 8.1, use version 1.0.0 (and check 1.x's readme as usage is slightly different):

$ composer require --dev esi/phpunit-coverage-check:^1.0

Phar

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/2.0.0/phpunit-coverage-check.phar"
wget -O phpunit-coverage-check.phar.asc "https://github.com/ericsizemore/phpunit-coverage-check/releases/download/2.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.

Install with Phive

You can also install the PHPUnit Coverage Check Phar with Phive.

If not already using Phive, you can read more about it here, also Phive installation and usage.

Usage

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>

If installed with Composer

$ php vendor/bin/coverage-check /path/to/clover.xml 100
$ php vendor/bin/coverage-check /path/to/clover.xml 100 --only-percentage
# -O for only-percentage works as well
$ php vendor/bin/coverage-check /path/to/clover.xml 100 -O
# -F or show-files will display coverage per file, formatted in a table
$ php vendor/bin/coverage-check /path/to/clover.xml 100 -F

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

If using the Phar

$ php phpunit-coverage-check.phar /path/to/clover.xml 100
$ php phpunit-coverage-check.phar /path/to/clover.xml 100 --only-percentage
# -O for only-percentage works as well
$ php phpunit-coverage-check.phar /path/to/clover.xml 100 -O
# -F or show-files will display coverage per file, formatted in a table
$ php phpunit-coverage-check.phar /path/to/clover.xml 100 -F

With --only-percentage (or -O) enabled, the CLI command will only return the resulting coverage percentage.

--show-files

With --show-files (or -F), --only-percentage will be ignored. This option parses the clover file for coverage information for each file in the project/package, determine coverage, and display the information in a table. For example:

Passing coverage

$ php coverage-check build/logs/clover.xml 90 -F

 ------------------------------------------------------------------- -------------------------- ----------
  File                                                                Elements (Covered/Total)   Coverage
 ------------------------------------------------------------------- -------------------------- ----------
  [...]\phpunit-coverage-check\src\Application.php                    12/12                      100.00%
  [...]\phpunit-coverage-check\src\Command\CoverageCheckCommand.php   94/94                      100.00%
  [...]\phpunit-coverage-check\src\CoverageCheck.php                  80/80                      100.00%
  [...]\phpunit-coverage-check\src\Style\CoverageCheckStyle.php       12/12                      100.00%
  [...]\phpunit-coverage-check\src\Utils.php                          39/39                      100.00%
 ------------------------------------------------------------------- -------------------------- ----------
  Overall Totals                                                      237/237                    100.00%
 ------------------------------------------------------------------- -------------------------- ----------

Mixed pass/fail coverage

$ php coverage-check tests/fixtures/clover.xml 90 -F

 ----------------------------- -------------------------- ----------
  File                          Elements (Covered/Total)   Coverage
 ----------------------------- -------------------------- ----------
  /tmp/Example/String.php       36/38                      94.74%
  /tmp/Example/StringList.php   20/24                      83.33%
 ----------------------------- -------------------------- ----------
  Overall Totals                56/62                      89.04%
 ----------------------------- -------------------------- ----------

About

Requirements

  • PHPUnit Coverage Check works with PHP 8.2.0 or above.

Submitting bugs and feature requests

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)

Contributing

See CONTRIBUTING

Backward Compatibility Promise

Author

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

License

PHPUnit Coverage Check is licensed under the MIT License.


  Files folder image Files  
File Role Description
Files folder image.github (3 files, 2 directories)
Files folder imagesrc (3 files, 2 directories)
Files folder imagetests (2 directories)
Accessible without login Plain text file .php-cs-fixer.dist.php Example Example script
Accessible without login Plain text file .scrutinizer.yml Data Auxiliary data
Accessible without login Plain text file backward-compatibility.md Data Auxiliary data
Accessible without login Plain text file box.json Data Auxiliary data
Accessible without login Plain text file CHANGELOG.md Data Auxiliary data
Accessible without login Plain text file CODE_OF_CONDUCT.md Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file composer.lock Data Auxiliary data
Accessible without login Plain text file CONTRIBUTING.md Data Auxiliary data
Accessible without login Plain text file coverage-check Example Example script
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file phpstan.neon Data Auxiliary data
Accessible without login Plain text file phpunit.xml Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation
Accessible without login Plain text file renovate.json Data Auxiliary data
Accessible without login Plain text file SECURITY.md Data Auxiliary data

  Files folder image Files  /  .github  
File Role Description
Files folder imageISSUE_TEMPLATE (3 files)
Files folder imageworkflows (2 files)
  Accessible without login Plain text file dependabot.yml Data Auxiliary data
  Accessible without login Plain text file FUNDING.yml Data Auxiliary data
  Accessible without login Plain text file pull_request_template.md Data Auxiliary data

  Files folder image Files  /  .github  /  ISSUE_TEMPLATE  
File Role Description
  Accessible without login Plain text file 1-bug_report.yml Data Auxiliary data
  Accessible without login Plain text file 2-feature_request.yml Data Auxiliary data
  Accessible without login Plain text file config.yml Data Auxiliary data

  Files folder image Files  /  .github  /  workflows  
File Role Description
  Accessible without login Plain text file main.yml Data Auxiliary data
  Accessible without login Plain text file tests.yml Data Auxiliary data

  Files folder image Files  /  src  
File Role Description
Files folder imageCommand (1 file)
Files folder imageStyle (1 file)
  Plain text file Application.php Class Class source
  Plain text file CoverageCheck.php Class Class source
  Plain text file Utils.php Class Class source

  Files folder image Files  /  src  /  Command  
File Role Description
  Plain text file CoverageCheckCommand.php Class Class source

  Files folder image Files  /  src  /  Style  
File Role Description
  Plain text file CoverageCheckStyle.php Class Class source

  Files folder image Files  /  tests  
File Role Description
Files folder imagefixtures (7 files)
Files folder imagesrc (1 file, 1 directory)

  Files folder image Files  /  tests  /  fixtures  
File Role Description
  Accessible without login Plain text file clover.xml Data Auxiliary data
  Accessible without login Plain text file empty.xml Data Auxiliary data
  Accessible without login Plain text file invalid_root_element.xml Data Auxiliary data
  Accessible without login Plain text file invalid_xml.xml Data Auxiliary data
  Accessible without login Plain text file no_children.xml Data Auxiliary data
  Accessible without login Plain text file no_project_metrics.xml Data Auxiliary data
  Accessible without login Plain text file self_clover.xml Data Auxiliary data

  Files folder image Files  /  tests  /  src  
File Role Description
Files folder imageCommand (1 file)
  Plain text file CoverageCheckTest.php Class Class source

  Files folder image Files  /  tests  /  src  /  Command  
File Role Description
  Plain text file CoverageCheckCommandTest.php Class Class source

 Version Control Unique User Downloads Download Rankings  
 100%
Total:13
This week:5
All time:11,278
This week:14Up