Download the PHP package shipmonk/coverage-guard without Composer

PHP Code Coverage Guard

Enforce code coverage in your CI with ease! Not by percentage, but target core functionality.

• 🎮 Game-changer: Innovative approach to code coverage enforcement!
• 💾 Legacy-friendly: Allows you to start enforcing for new code only!
• ⚙️ Extensible: You specify what must be covered!
• 🕸️ Lightweight: Only depends on nikic/php-parser
• 🍰 Easy-to-use: No config needed for first try

This tool helps ensure that certain code blocks are covered by tests, typically core methods in Facades, Controllers, and other key areas of your application.

Installation

Example usage

Example output:

In real application, you will probably use phpunit.xml to configure PHPUnit coverage:

To collect coverage, you can pick traditional XDebug or performant PCOV extension.

Enforce coverage for new code only

• When patch is provided, this tool will only analyse changed files and methods and won't report violations from elsewhere.
• This allows you to gradually enforce code coverage for new code only.

Configuration

• Create a coverage-guard.php file in your project root to customize behavior and set up your CoverageRules.
  • You can generate quick-start one by vendor/bin/coverage-guard init
• The config file must return an instance of ShipMonk\CoverageGuard\Config
• Here is what you can configure:

Advanced usage:

• For custom enforcement logic, implement CoverageRule and pass it to Config::addRule() method:
  • Inspire by prepared EnforceCoverageForMethodsRule or usages in the wild:
    • own coverage config
    • dead-code-detector
    • phpstan-rules

What can you enforce:

The CodeBlock class passed to CoverageRule is aware which line is executable, changed and covered. Also, you can use reflection to pinpoint your rules. This allows you to setup huge variety of rules, examples:

• All newly created methods must have some coverage
• When a method is changed by more than 50%, it must have at least 50% coverage
• All methods in your codebase longer than 10 executable lines must have some coverage
• All Controller methods must have at least 50% coverage
• Every method must be tested unless custom #[NoCoverageAllowed] attribute is used
• ...

Global CLI options

• --help show generic help (or command help when combined with command name)
• --no-color to disable colors (NO_COLOR env is also supported)
• --color to force colors even when output is not a TTY

Run vendor/bin/coverage-guard <command> --help for command-specific options.

Supported PHPUnit coverage formats

Commands

check

• Main command to enforce code coverage rules on your codebase as described above.

Options:

• --verbose – show detailed processing information
• --patch – path to git diff, to check coverage only for changed files & methods
• --config – path to custom PHP config

merge & convert

• Merging multiple coverage files into a single file is useful when running tests in parallel CI jobs.
• Please note those commands do not maintain all data from original XMLs
  • It only produces minimal XML files while maintaining usability by PHPStorm, GitLab and Coverage Guard
• Input formats: clover, cobertura, php (autodetected)
• Output formats: clover, cobertura

Options:

• --output-format – output format (clover or cobertura)
• --indent – output XML indentation (defaults to 4 spaces); for tabs use --indent=$'\t'
• --config – path to custom PHP config

patch-coverage

• Calculate coverage percentage for lines changed in a patch file.
• Handy for GitLab coverage pattern: coverage: '/Coverage:\s+(\d+\.\d+%)/'
  • You will see coverage of changed lines in your MR detail

Options:

• --patch – path to diff file (required)
• --config – path to custom PHP config

Output example:

init

• Generates sample coverage-guard.php configuration file in your current directory.
  • You should customize it to your needs.

Optional dependencies

• Libraries:
  • phpunit/php-code-coverage for loading coverage cov files
  • sebastian/diff for processing diff/patch files
• PHP extensions:
  • ext-libxml and ext-simplexml for loading coverage XML files
  • ext-dom for check and merge commands
  • ext-tokenizer to see syntax highlighted code blocks

Contributing

• Check your code by composer check
• Autofix coding-style by composer fix:cs
• All functionality must be tested