Phpspec Code Coverage Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev leanphp/phpspec-code-coverage
   

   Register the service provider in config/app.php (if not auto-discovered):

   'providers' => [
       // ...
       LeanPhp\PhpSpecCodeCoverage\PhpSpecCodeCoverageServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="LeanPhp\PhpSpecCodeCoverage\PhpSpecCodeCoverageServiceProvider" --tag="config"
   

   Update config/phpspec-code-coverage.php to match your project’s needs (e.g., coverage thresholds, report paths).

3. First Run Execute PhpSpec with coverage:

   ./vendor/bin/phpspec run --format=leanphp
   

   Reports will generate in the configured output directory (default: storage/coverage).

First Use Case: Enforcing Coverage in a CI Pipeline

• Add a step in your CI (e.g., GitHub Actions) to run:

  ./vendor/bin/phpspec run --format=leanphp --min=80
  

  (Replace 80 with your desired threshold.)
• Fail the build if coverage drops below the threshold.

Implementation Patterns

Workflows

1. Integrating with Laravel’s Testing

   • Use the package alongside Laravel’s phpunit coverage tools for consistency.
   • Example: Run PhpSpec coverage in a separate CI job or script:

     ./vendor/bin/phpspec run --format=leanphp --min=70 && ./vendor/bin/phpunit --coverage-text
     

2. Custom Report Generation

   • Extend the default CLI formatter to output JSON or HTML:

     // app/Console/Commands/GenerateCoverageReport.php
     use LeanPhp\PhpSpecCodeCoverage\Formatters\CliFormatter;
     
     class GenerateCoverageReport extends Command {
         protected function handle() {
             $formatter = new CliFormatter();
             $coverage = $formatter->format($this->getPhpSpecCoverageData());
             // Custom logic (e.g., save to DB, Slack notification)
         }
     }
     

3. Dynamic Thresholds

   • Override thresholds per spec file or suite:

     # phpspec.yml
     extensions:
         LeanPhp\PhpSpecCodeCoverage\PhpSpecCodeCoverageExtension:
             min: 85
             files:
                 spec/FeatureSpec.php: 90
     

Integration Tips

• Laravel Mix/Webpack: Embed coverage reports in your frontend dashboard by fetching JSON output via an API route.
• Laravel Scout: Use coverage data to prioritize testable features in search results.
• Laravel Horizon: Monitor coverage trends over time by logging reports to a database table (e.g., coverage_runs).

Gotchas and Tips

Pitfalls

1. False Positives/Negatives

   • The package may misreport coverage for:
     • Dynamic classes (e.g., generated by Doctrine or Laravel’s make:model).
     • Traits or interfaces not directly tested in PhpSpec.
   • Fix: Exclude paths in config/phpspec-code-coverage.php:

     'exclude' => [
         'app/Traits/*',
         'app/Interfaces/*',
     ],
     

2. Performance Overhead

   • Running coverage on large suites (e.g., 500+ specs) can slow down CI.
   • Fix: Parallelize specs with --parallel or run coverage only on changed files:

     ./vendor/bin/phpspec run --format=leanphp --files=spec/ChangedSpec.php
     

3. Config Overrides

   • CLI flags (e.g., --min) override phpspec.yml settings.
   • Tip: Document this in your team’s testing guidelines to avoid confusion.

Debugging

• Verbose Output: Enable debug mode in phpspec.yml:

  extensions:
      LeanPhp\PhpSpecCodeCoverage\PhpSpecCodeCoverageExtension:
          debug: true
  

  Logs will appear in storage/logs/phpspec-coverage.log.

• Coverage Artifacts: Clear old reports before running:

  rm -rf storage/coverage/*
  

Extension Points

1. Custom Formatters

   • Implement LeanPhp\PhpSpecCodeCoverage\FormatterInterface to create new report types (e.g., JUnit XML for CI tools):

     class JUnitFormatter implements FormatterInterface {
         public function format(array $coverageData): string {
             // Generate JUnit-compatible XML
         }
     }
     

   • Register in phpspec.yml:

     formatters:
         leanphp-junit: LeanPhp\PhpSpecCodeCoverage\Formatters\JUnitFormatter
     

2. Hooks

   • Use Laravel’s events to trigger actions on coverage changes:

     // app/Providers/EventServiceProvider.php
     public function boot() {
         event(new \LeanPhp\PhpSpecCodeCoverage\Events\CoverageGenerated(
             $coverageData
         ));
     }
     

3. Laravel Service Container

   • Bind the coverage service manually for testing:

     $this->app->bind(\LeanPhp\PhpSpecCodeCoverage\CoverageAnalyzer::class, function () {
         return new \LeanPhp\PhpSpecCodeCoverage\CoverageAnalyzer(
             config('phpspec-code-coverage')
         );
     });