Getting Started

Minimal Setup

Install the package:

composer require --dev dvdoug/behat-code-coverage

Enable the extension in behat.yml:

extensions:
    LeanPHP\Behat\CodeCoverage\CodeCoverageExtension:
        format: [clover, html]
        output: ./build/coverage

Run Behat with coverage:
```
./vendor/bin/behat --colors
```
Reports will be generated in ./build/coverage.

First Use Case

Generate an HTML report to visualize test coverage in your Laravel application:

extensions:
    LeanPHP\Behat\CodeCoverage\CodeCoverageExtension:
        format: [html]
        output: ./storage/logs/behat-coverage
        html:
            directory: ./storage/logs/behat-coverage/html
            colors: true

Access the report at http://localhost/storage/logs/behat-coverage/html/index.html after running Behat.

Implementation Patterns

Workflow Integration

CI/CD Pipeline:

Add coverage checks in GitHub Actions:

- name: Run Behat with Coverage
  run: ./vendor/bin/behat --config=behat.yml --no-interaction --colors
- name: Upload Coverage Report
  uses: actions/upload-artifact@v3
  with:
    name: coverage-report
    path: ./storage/logs/behat-coverage

Fail builds if coverage drops below a threshold (e.g., using php-coveralls/php-coveralls).

Local Development:
- Use --no-coverage for faster local runs:
```
./vendor/bin/behat --no-coverage
```
- Generate reports on demand:
```
./vendor/bin/behat --config=behat-coverage.yml
```

Configuration Patterns

Multi-Format Reports:

extensions:
    LeanPHP\Behat\CodeCoverage\CodeCoverageExtension:
        reports:
            clover: ./storage/logs/clover.xml
            html: ./storage/logs/html
            cobertura: ./storage/logs/cobertura.xml
            openclover: ./storage/logs/openclover.xml

Filtering Coverage:

extensions:
    LeanPHP\Behat\CodeCoverage\CodeCoverageExtension:
        filter:
            include:
                - app/Http/Controllers/
                - app/Services/
            exclude:
                - app/Providers/*
                - tests/*
        output: ./storage/logs/coverage

Branch/Path Coverage (Xdebug required):

extensions:
    LeanPHP\Behat\CodeCoverage\CodeCoverageExtension:
        branchAndPathCoverage: true
        output: ./storage/logs/branch-coverage

Laravel-Specific Tips

Artisan Integration: Create a custom Artisan command to run Behat with coverage:

// app/Console/Commands/RunBehatWithCoverage.php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Symfony\Component\Process\Process;

class RunBehatWithCoverage extends Command
{
    protected $signature = 'behat:coverage';
    protected $description = 'Run Behat tests with code coverage';

    public function handle()
    {
        $process = new Process(['./vendor/bin/behat', '--config=behat.yml']);
        $process->run();
        $this->output->write($process->getOutput());
    }
}

Run with:

php artisan behat:coverage

Storage Paths: Use Laravel’s storage paths for consistency:

extensions:
    LeanPHP\Behat\CodeCoverage\CodeCoverageExtension:
        output: ./storage/app/behat-coverage

Gotchas and Tips

Common Pitfalls

Missing Coverage Drivers:
- Symptom: Warnings like No coverage driver found.
- Fix: Ensure xdebug or pcov is installed and enabled:
```
pecl install xdebug
```
  Add to php.ini:
```
zend_extension=xdebug.so
xdebug.mode=coverage
```
Path Issues:
- Symptom: Reports generated in unexpected locations or paths not found.
- Fix: Use absolute paths or Laravel’s storage_path() helper:
```
output: ./storage/app/behat-coverage
```
  Or in PHP:
```
$config['output'] = storage_path('app/behat-coverage');
```
Xdebug Conflicts:
- Symptom: Errors when both pcov and xdebug are enabled.
- Fix: Disable xdebug.coverage_enable or use pcov exclusively:
```
xdebug.coverage_enable=0
```
Cache Issues:
- Symptom: Stale coverage data or slow runs.
- Fix: Clear the cache:
```
rm -rf ./var/behat-code-coverage-cache
```
  Or configure a custom cache path:
```
cache: ./storage/framework/cache/behat-coverage
```

Debugging Tips

Verbose Output: Run Behat with -vvv to debug extension initialization:
```
./vendor/bin/behat -vvv
```
Check Configuration: Validate your behat.yml using the --dry-run flag:
```
./vendor/bin/behat --dry-run
```

Report Validation: Use tools like php-coveralls to validate report formats:

composer require --dev php-coveralls/php-coveralls
vendor/bin/coveralls --coverage_by_file --json_path=./storage/logs/clover.xml

Extension Points

Custom Report Formats: Extend the package by adding new report formats. Example for json:
```
reports:
    json: ./storage/logs/coverage.json
```
Ensure phpunit/php-code-coverage supports the format (check their docs).

Pre/Post-Test Hooks: Use Behat hooks to trigger coverage reports dynamically:

// features/bootstrap/FeatureContext.php
use LeanPHP\Behat\CodeCoverage\CodeCoverageExtension;
use Behat\Behat\Event\SuiteEvent;

$eventDispatcher->addListener(SuiteEvent::BEFORE_SUITE, function (SuiteEvent $event) {
    $extension = $event->getSuite()->getEnvironment()->getExtension('code_coverage');
    if ($extension instanceof CodeCoverageExtension) {
        $extension->setOutput(storage_path('logs/behat-coverage-dynamic'));
    }
});

CI-Specific Configs: Use environment variables to switch configurations:

# behat.yml
extensions:
    LeanPHP\Behat\CodeCoverage\CodeCoverageExtension:
        output: '%env(BEHAT_COVERAGE_OUTPUT, ./storage/logs/coverage)%'

Set in CI:

export BEHAT_COVERAGE_OUTPUT=./build/coverage

Laravel-Specific Quirks

Service Provider Conflicts: If using Laravel’s BehatTestCase, ensure the extension is loaded after Behat’s service provider:
```
// config/behat.php
'extensions' => [
    LeanPHP\Behat\CodeCoverage\CodeCoverageExtension::class,
],
```
Storage Permissions: Ensure the coverage output directory is writable:
```
chmod -R 775 ./storage/logs
```
Docker Environments: For Dockerized Laravel apps, ensure xdebug or pcov is installed in the container:
```
RUN pecl install xdebug && docker-php-ext-enable xdebug
```

Behat Code Coverage Laravel Package