thor-juhasz/phpunit-coverage-check

A PHPUnit test coverage checker

v0.3.0 2021-07-04 22:21 UTC

Requires

• php: >=7.4
• ext-bcmath: *
• ext-simplexml: *
• symfony/console: 4.*|5.*

Requires (Dev)

• phpunit/phpunit: ^9
• vimeo/psalm: ^4.8

MIT

• Thor Juhasz

README

A PHPUnit test coverage checker.

This command will parse a clover.xml report file (generated by PHPUnit), to check that the test coverage meets a certain threshold (80% by default).

This library is loosely based on johanvanhelden's test coverage check.

Table of contents

Table of contents

• Installation
• Usage
  • Use in GitHub workflow
  • Run manually
• Arguments
  • filename
• Options
  • threshold
  • metric
  • suppress-errors
• Output

Installation

Run this in your projects root directory:

composer require --dev thor-juhasz/phpunit-coverage-check

This will add a new PHP binary to your vendor/bin/ directory, named phpunit-coverage-check.

Usage

Use in GitHub workflow

To use this library in a GitHub CI workflow, make sure to generate a clover.xml report file when running phpunit:

      - name: Run PHPUnit Tests
        run: ./vendor/bin/phpunit --coverage-clover clover.xml

Then simply add this after the step than runs phpunit:

      - name: Test coverage
        run: ./vendor/bin/phpunit-coverage-check -t 100 clover.xml

Run manually

Generate a clover.xml report file with PHPUnit:

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

Then you can run the binary provided by this library, passing the name of the clover.xml file as the first argument:

./vendor/bin/phpunit-coverage-check clover.xml

Arguments

filename (required)

The filename of the clover coverage XML file.

Example:

./vendor/bin/phpunit-coverage-check clover.xml

Options

threshold (optional)

Default value: 80

The threshold determines the lower value of acceptable test coverage. You can pass your desired threshold using --threshold N or -t N for short, where N is a number ranging from 0 to 100:

Example:

# Requires 100% coverage
./vendor/bin/phpunit-coverage-check --threshold 100 clover.xml
# Requires 50% coverage
./vendor/bin/phpunit-coverage-check -t 50 clover.xml
# By default when passing no threshold option, it will require 80% coverage
./vendor/bin/phpunit-coverage-check clover.xml

metric (optional)

Default value: elements

You can specify here which metric you want to use to read the code coverage. The supported metrics are:

• elements
• statements
• methods

Example:

./vendor/bin/phpunit-coverage-check --metric statements clover.xml
./vendor/bin/phpunit-coverage-check -m methods clover.xml
# By default when passing no metric option, it will use elements
./vendor/bin/phpunit-coverage-check clover.xml

suppress-errors (optional)

When the code coverage reported in the clover XML report is under the specified threshold, the command will exit with code 1. When used in a CI workflow, this results in that job failing.

If you would like to use this tool in a CI workflow, without failing the job, you can pass the --suppress-errors option (or -s for short).

Example:

      # Even if the coverage is under the threshold, this will not fail the job
      - name: Test coverage
        run: ./vendor/bin/phpunit-coverage-check -t 100 clover.xml

Output

Example outputs:

# When coverage is 100%, and default threshold used.
$ ./vendor/bin/phpunit-clover-test-coverage-check clover.xml
[OK] Code coverage is 100%, which is acceptable (requires >= 80% coverage)

# When coverage is 100%, and threshold is set to 100%.
$ ./vendor/bin/phpunit-clover-test-coverage-check clover.xml
[OK] Code coverage is 100%, which is acceptable (requires full coverage)

# When coverage is 1%, and default threshold used.
$ ./src/test-coverage-checker.php clover.xml
[ERROR] Code coverage is 1%, which is not acceptable (requires >= 80% coverage)

# When coverage is 1%, and threshold is set to 100%.
$ ./src/test-coverage-checker.php clover.xml
[ERROR] Code coverage is 1%, which is not acceptable (requires full coverage)