Testing

/laravel-agent:test:coverage

Run tests with coverage report and analysis

Overview

The /test:coverage command runs your test suite and generates a comprehensive coverage report. It checks for required coverage drivers (Xdebug or PCOV), runs tests with coverage analysis, and provides detailed insights into which parts of your codebase need more test coverage.

Usage

/laravel-agent:test:coverage [min-coverage] [format]

Arguments

  • min-coverage (optional) - Minimum coverage percentage required (default: 80)
  • format (optional) - Output format: text or html (default: text)

Examples

# Run with default 80% minimum coverage
/laravel-agent:test:coverage

# Require 90% coverage
/laravel-agent:test:coverage 90

# Generate HTML coverage report
/laravel-agent:test:coverage 80 html

How It Works

The command follows a systematic process to generate coverage reports:

1. Check Requirements

First, it verifies that a coverage driver is installed:

php -m | grep xdebug && echo "XDEBUG=yes" || echo "XDEBUG=no"
php -m | grep pcov && echo "PCOV=yes" || echo "PCOV=no"

2. Run Tests with Coverage

Executes tests with coverage enabled using your test framework:

# For Pest PHP
vendor/bin/pest --coverage --min=80

# For PHPUnit
vendor/bin/phpunit --coverage-text --coverage-html=coverage

3. Generate Report

Provides a detailed analysis of test coverage:

## Coverage Report

### Summary
- Lines: 85.3%
- Functions: 92.1%
- Classes: 88.0%

### Uncovered Files
| File | Coverage |
|------|----------|
| app/Services/PaymentService.php | 45% |
| app/Actions/ProcessOrder.php | 62% |

### Recommendations
1. Add tests for PaymentService::refund()
2. Cover edge cases in ProcessOrder

Coverage Drivers

Two main drivers are available for PHP code coverage:

PCOV (Recommended)

PCOV is faster than Xdebug when you only need coverage data (not debugging):

composer require --dev pcov/clobber

PCOV is lightweight and specifically designed for code coverage, making it the preferred choice for CI/CD pipelines and local development when debugging isn't needed.

Xdebug

Xdebug provides full debugging capabilities plus coverage:

xdebug.mode=coverage

Use Xdebug when you need both debugging and coverage features. Note that it's slower than PCOV but offers more comprehensive development tools.

Coverage Metrics Explained

Metric Description Good Target
Lines Percentage of code lines executed by tests 80-90%
Functions Percentage of functions/methods called by tests 85-95%
Classes Percentage of classes with at least one test 85-95%

Best Practices

  1. Set realistic targets - 80% is a good baseline; 100% is often impractical
  2. Focus on critical paths - Prioritize business logic over boilerplate
  3. Use HTML reports - Visual reports help identify specific uncovered lines
  4. Run in CI/CD - Enforce minimum coverage in your deployment pipeline
  5. Track trends - Monitor coverage over time, not just absolute numbers

HTML Report Output

When generating HTML reports, files are created in the coverage/ directory:

coverage/
├── index.html           # Main coverage dashboard
├── dashboard.html       # Coverage metrics overview
└── [namespace folders]  # Per-file coverage details

Open coverage/index.html in your browser to explore line-by-line coverage with color-coded indicators.

See Also