Phpunit File Coverage Inspection Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev digitalrevolution/phpunit-file-coverage-inspection
   

2. Generate a phpfci.xml config file in your project root using:

   php vendor/bin/phpfci baseline coverage.xml --config ./phpfci.xml --baseDir ./src
   

   (Replace coverage.xml with your actual PHPUnit coverage report path.)

3. Run inspection against your coverage report:

   php vendor/bin/phpfci inspect coverage.xml
   

   (Outputs violations to stdout by default.)

First Use Case: Enforcing Per-File Coverage

• Configure phpfci.xml to set file/directory-specific thresholds (e.g., src/App/Commands at 95%, src/App/Jobs at 100%).
• Integrate into CI/CD to fail builds if thresholds are violated:

  php vendor/bin/phpfci inspect coverage.xml --exit-code-on-failure
  

Implementation Patterns

1. CI/CD Integration

• GitLab CI Example:

  test:
    script:
      - php vendor/bin/phpunit --coverage-clover coverage.xml
      - php vendor/bin/phpfci inspect coverage.xml --reportGitlab=gl-coverage-errors.json
    artifacts:
      when: always
      reports:
        codequality: gl-coverage-errors.json
  

• GitHub Actions:

  - name: Run coverage inspection
    run: |
      php vendor/bin/phpfci inspect coverage.xml --reportCheckstyle=checkstyle.xml
      if [ $? -ne 0 ]; exit 1;
  

2. Dynamic Baseline Generation

• Use baseline to auto-generate rules from existing coverage:

  php vendor/bin/phpfci baseline coverage.xml --config phpfci.xml --baseDir ./src
  

  (Adjust thresholds manually afterward in phpfci.xml.)

3. Multi-File Coverage

• Inspect multiple coverage reports (e.g., unit + feature tests):

  php vendor/bin/phpfci inspect unit-coverage.xml feature-coverage.xml
  

4. Laravel-Specific Workflow

• Composer Script (in composer.json):

  "scripts": {
    "test:coverage": "phpunit --coverage-clover=coverage.xml",
    "test:inspect": "php vendor/bin/phpfci inspect coverage.xml --exit-code-on-failure"
  }
  

  Run with:

  composer test:coverage && composer test:inspect
  

5. Custom Output Formats

• Checkstyle for IDE Integration:

  php vendor/bin/phpfci inspect coverage.xml --reportCheckstyle=reports/checkstyle.xml
  

• GitLab Code Quality:

  php vendor/bin/phpfci inspect coverage.xml --reportGitlab=gl-errors.json
  

Gotchas and Tips

Pitfalls

1. Path Resolution Issues:

   • Ensure --baseDir matches the project root (not src/). Paths in coverage.xml must resolve correctly.
   • Fix: Use absolute paths or verify relative paths in phpfci.xml.

2. Overlapping Rules:

   • File rules override directory rules, but directory rules apply to subdirectories.
   • Example: A src/App/ rule at 90% won’t apply to src/App/Exceptions/ if it has a 100% rule.

3. Method Coverage Strictness:

   • allow-uncovered-methods="false" (default) fails if any method has 0% coverage, even if file coverage is met.
   • Workaround: Use <ignore-uncovered-methods> for specific files.

4. Baseline Mismatches:

   • Running baseline with inconsistent coverage files (e.g., unit vs. feature tests) may generate misleading rules.
   • Tip: Generate baselines per test suite separately.

5. PHPUnit Version Compatibility:

   • The package supports PHPUnit 10–12. Older versions may break path parsing.
   • Fix: Update PHPUnit or pin the package version (e.g., ^2.2.0).

Debugging Tips

• Dry Run: Use --reportText to preview violations before failing CI:

  php vendor/bin/phpfci inspect coverage.xml --reportText > violations.txt
  

• Validate XML: Ensure phpfci.xml is valid against the schema.
• Check Coverage Paths: Run phpunit --coverage-text to verify file paths match your project structure.

Extension Points

1. Custom Validators:

   • Extend the package by implementing a CoverageValidator interface to add logic (e.g., exclude vendor files).

2. Post-Inspection Hooks:

   • Parse --reportGitlab output to trigger Slack notifications or annotate PRs:

     $errors = json_decode(file_get_contents('gl-errors.json'), true);
     // Custom logic (e.g., Slack API call)
     

3. Symfony Console Integration:

   • Use the underlying PhpFciCommand class in Laravel Artisan commands for programmatic access:

     use DigitalRevolution\PhpFci\Command\PhpFciCommand;
     $command = new PhpFciCommand();
     $command->run(new ArrayInput(['inspect', 'coverage.xml']), new NullOutput());
     

Performance

• Large Codebases: Inspection scales linearly with file count. For >10K files, consider:
  • Splitting tests into smaller suites (e.g., unit/, feature/).
  • Using --baseDir to limit path resolution overhead.