Covelyzer Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require --dev vstelmakh/covelyzer
   

   Add to composer.json under require-dev if not using Composer globally.

2. First Run Generate a Clover coverage report from PHPUnit:

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

   Then analyze it with Covelyzer:

   ./vendor/bin/covelyzer coverage.clover
   

3. Basic Configuration Create a covelyzer.php config file in your project root (or use defaults):

   return [
       'threshold' => 80, // Default coverage threshold (0-100)
       'exclude' => [
           'tests/',
           'vendor/',
       ],
       'format' => 'text', // Options: 'text', 'json', 'xml'
   ];
   

First Use Case

Analyze test coverage for a single class:

./vendor/bin/covelyzer --class=UserTest coverage.clover

Check if coverage meets your team’s threshold (e.g., 80%) and identify untested methods.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add Covelyzer to your CI (e.g., GitHub Actions) to fail builds if coverage drops:

   - name: Check coverage
     run: ./vendor/bin/covelyzer coverage.clover --fail-on-threshold
   

2. Pre-Commit Hook Use with tools like husky or pre-commit to enforce coverage locally:

   ./vendor/bin/covelyzer coverage.clover --threshold=90
   

3. Custom Reports Generate JSON/XML for programmatic use:

   ./vendor/bin/covelyzer --format=json coverage.clover > coverage.json
   

   Parse in PHP:

   $report = json_decode(file_get_contents('coverage.json'), true);
   $lowCoverageClasses = array_filter($report['classes'], fn($c) => $c['coverage'] < 80);
   

Common Patterns

• Exclude Directories:

  'exclude' => ['tests/Unit/', 'tests/Feature/Integration/'],
  

• Focus on Specific Files:

  ./vendor/bin/covelyzer --file=src/Models/User.php coverage.clover
  

• Compare Reports: Use --previous=previous.clover to compare with a baseline report.

Gotchas and Tips

Pitfalls

1. Clover Format Dependency

   • Covelyzer only works with Clover format. Ensure PHPUnit generates it:

     phpunit --coverage-clover=coverage.clover
     

   • Fix: Add --coverage-clover to your PHPUnit config or .phpunit.xml.

2. Threshold Misconfiguration

   • Default threshold is 80. If set too high (e.g., 99), legitimate edge cases may fail.
   • Tip: Start with 70 for new projects, then incrementally raise it.

3. Exclusion Overkill

   • Over-excluding paths (e.g., src/) may hide critical gaps.
   • Tip: Use --verbose to debug excluded files:

     ./vendor/bin/covelyzer --verbose coverage.clover
     

4. Performance on Large Codebases

   • Parsing massive Clover files (e.g., 10K+ lines) may slow down analysis.
   • Tip: Run in parallel with --parallel (if supported) or split reports by module.

Debugging

• Silent Failures: Covelyzer exits with 0 even if coverage fails. Use --fail-on-threshold in CI to enforce it.
• False Positives: Static methods or __construct() may show 0% coverage. Exclude them explicitly:

  'exclude_methods' => ['__construct', 'staticMethod'],
  

Extension Points

1. Custom Rules Extend the analyzer by subclassing Covelyzer\Analyzer and overriding analyze():

   class CustomAnalyzer extends \Covelyzer\Analyzer {
       protected function analyze($report) {
           // Add logic (e.g., check for uncovered private methods)
       }
   }
   

   Register in covelyzer.php:

   'analyzer' => \App\CustomAnalyzer::class,
   

2. Output Plugins Add custom output formats by implementing Covelyzer\Output\OutputInterface:

   class SlackOutput implements OutputInterface {
       public function output($data) {
           // Send to Slack API
       }
   }
   

   Bind in config:

   'output' => \App\SlackOutput::class,
   

3. Integration with PHPStan Combine with PHPStan’s coverage rules for stricter analysis:

   ./vendor/bin/phpstan analyse --level=max --coverage --coverage-sources=src
   ./vendor/bin/covelyzer coverage.clover