README

Display the code coverage for a project using a clover.xml file, optionally enforcing a minimum code coverage percentage.

This package is designed to be used in your CI/CD or automated testing process (i.e., using GitHub Workflows).

The concept for this package is based on this article.

Note on PHP 7.x support: If you are using PHP 7.x, use the 1.x version of this package.

Installation

composer require permafrost-dev/coverage-check --dev

Usage

Specify a valid clover.xml file and (optionally) a minimum coverage percentage to require using the --require or -r flag. A percentage can be either a whole number (integer) or a decimal (float).

If you specify the --require/-r flag, the check will fail if coverage percent is below the value you provide, and the process exit code will be non-zero.

If you don't specify the --require/-r flag, only the percentage of code coverage will be displayed and the exit code will always be zero.

./vendor/bin/coverage-check clover.xml
./vendor/bin/coverage-check clover.xml --require=50
./vendor/bin/coverage-check clover.xml -r 80.5
./vendor/bin/coverage-check clover.xml -m statement -r 75
./vendor/bin/coverage-check clover.xml --precision=1

Available Options

Option	Description
`--coverage-only` or `-C`	Only display the code coverage value
`--metric` or `-m` `<name>`	Use the specified metric field for calculating coverage. Valid values are `element` (default), `method`, or `statement`
`--precision` or `-p` `<value>`	Use the specified precision when calculating the code coverage percentage, where `<value>` is an integer (default: 4)
`--require` or `-r` `<value>`	Enforce a minimum code coverage value, where `<value>` is an integer or decimal value

Metric fields

The field that is used to calculate code coverage can be specified using the --metric=<name> or -m <name> option.

Valid field names are element (the default), statement, and method.

Generating clover-format coverage files

PHPUnit can generate coverage reports in clover format:

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

Sample Github Workflow

name: run-tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: true
      matrix:
        os: [ubuntu-latest]
        php: [8.1, 8.0, 7.4, 7.3]

    name: P${{ matrix.php }} - ${{ matrix.os }}

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, intl, iconv, fileinfo
          coverage: pcov

      - name: Setup problem matchers
        run: |
          echo "::add-matcher::${{ runner.tool_cache }}/php.json"
          echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"

      - name: Install dependencies
        run: composer update --prefer-stable --prefer-dist --no-interaction

      - name: Execute tests
        run: ./vendor/bin/phpunit --coverage-clover clover.xml

      - name: Enforce 75% code coverage
        run: ./vendor/bin/coverage-check clover.xml --require=75 --precision=2

Testing

./vendor/bin/phpunit

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

permafrost-dev / coverage-check

Maintainers

Details