Phpunit Coverage Check Laravel Package

Getting Started

Minimal Steps

1. Install the Package Add to your composer.json:

   composer require --dev rregeer/phpunit-coverage-check
   

2. Generate a Clover Report Run PHPUnit with coverage and clover output:

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

3. Run the Coverage Check Execute the script with the clover file and a threshold (e.g., 80%):

   vendor/bin/coverage-check clover.xml 80
   

First Use Case

• CI/CD Pipeline Integration: Fail builds if coverage drops below a threshold (e.g., 80%).
• Pre-Commit Hook: Block commits with insufficient test coverage.

Implementation Patterns

Workflows

1. CI/CD Integration Add to your CI script (e.g., .github/workflows/ci.yml):

   - name: Run PHPUnit
     run: vendor/bin/phpunit --coverage-clover clover.xml
   - name: Check Coverage
     run: vendor/bin/coverage-check clover.xml 80
   

   Exit code 1 will fail the pipeline.

2. Pre-Commit Hook Use with tools like husky or pre-commit:

   # .huskyrc.js
   {
     "hooks": {
       "pre-commit": "vendor/bin/phpunit --coverage-clover clover.xml && vendor/bin/coverage-check clover.xml 80"
     }
   }
   

3. Laravel-Specific Workflow

   • Custom Artisan Command: Extend the check for Laravel-specific logic (e.g., exclude vendor/ or tests/ from coverage).
   • GitHub Actions:

     - name: Laravel Coverage Check
       run: |
         php artisan test --coverage-clover=clover.xml
         vendor/bin/coverage-check clover.xml 85
     

Integration Tips

• Dynamic Thresholds: Use environment variables for thresholds (e.g., COVERAGE_THRESHOLD).

  vendor/bin/coverage-check clover.xml $COVERAGE_THRESHOLD
  

• Parallel Testing: Run PHPUnit in parallel (e.g., --parallel) and aggregate clover reports before checking.
• Custom Reports: Generate clover reports for specific suites (e.g., --filter=Feature) and apply suite-specific thresholds.

Gotchas and Tips

Pitfalls

1. Clover File Path

   • Hardcoding paths (e.g., clover.xml) may break across environments. Use relative paths or config files.
   • Fix: Store the clover path in .env:

     COVERAGE_CLOVER_PATH=storage/logs/clover.xml
     

     Then reference it dynamically in scripts.

2. Threshold Precision

   • The script rounds coverage to 2 decimal places. A threshold of 80 checks for ≥ 80.00%.
   • Tip: Use 80.0 for explicit decimal handling (though the package may ignore decimals).

3. Exit Codes

   • Exit code 1 = failure (coverage below threshold).
   • Exit code 0 = success (coverage meets threshold).
   • Debugging: Check exit codes in CI/CD logs to diagnose failures.

4. PHPUnit Configuration

   • Ensure <coverage> is properly configured in phpunit.xml:

     <coverage>
       <include>src/*</include>
       <exclude>src/Exceptions/*</exclude>
     </coverage>
     

   • Misconfigured includes/excludes can skew coverage results.

Debugging

1. Dry Runs Use --only-percentage to verify coverage before enforcing thresholds:

   vendor/bin/coverage-check clover.xml 80 --only-percentage
   

   Outputs only the percentage (e.g., 78.50%), helping debug without failing.

2. Log Clover Details Inspect the clover.xml file directly for discrepancies:

   xmllint --format clover.xml  # Pretty-print XML
   

   Look for unexpected files or line counts.

3. CI Debugging Cache the clover file as an artifact in CI to inspect after failures:

   - name: Upload Clover Artifact
     uses: actions/upload-artifact@v3
     if: failure()
     with:
       name: clover-report
       path: clover.xml
   

Extension Points

1. Custom Validation Logic Extend the script by wrapping it in a PHP class (e.g., app/Console/Commands/CoverageCheck.php):

   use Symfony\Component\Process\Process;
   use Symfony\Component\Process\Exception\ProcessFailedException;
   
   class CoverageCheck extends Command {
       protected function handle() {
           $process = new Process(['vendor/bin/coverage-check', 'clover.xml', '80']);
           $process->run();
           if (!$process->isSuccessful()) {
               throw new ProcessFailedException($process);
           }
       }
   }
   

   Add pre/post-check logic (e.g., Slack notifications).

2. Composite Reports Merge multiple clover files (e.g., from parallel tests) before checking:

   vendor/bin/phpunit --coverage-clover=clover1.xml --testdox-html
   vendor/bin/phpunit --coverage-clover=clover2.xml --testdox-html
   php merge-clover.php clover1.xml clover2.xml merged.xml
   vendor/bin/coverage-check merged.xml 80
   

   Use tools like php-coveralls for merging.

3. Laravel Service Provider Register a global coverage check listener in AppServiceProvider:

   public function boot() {
       if (app()->environment('testing')) {
           $this->registerCoverageCheck();
       }
   }
   
   protected function registerCoverageCheck() {
       Artisan::addCommand(new \App\Console\Commands\CoverageCheck);
   }
   

   Trigger checks via php artisan coverage:check.