Coverage Guard Laravel Package

Getting Started

Install with composer require --dev shipmonk/coverage-guard. Start by generating a config with vendor/bin/coverage-guard init, then run your test suite with coverage (XDEBUG_MODE=coverage vendor/bin/phpunit tests --coverage-clover clover.xml) and validate with vendor/bin/coverage-guard check clover.xml. The tool works out-of-the-box with sensible defaults (no config needed for first try), enforcing coverage on all methods ≥5 executable lines with ≥50% coverage.

Implementation Patterns

• Gradual rollout: Use git diff master...HEAD > changes.patch && vendor/bin/coverage-guard check clover.xml --patch changes.patch to enforce coverage only on new/modified code—ideal for legacy apps.
• CI integration: Add the check command after PHPUnit in your CI pipeline (e.g., in GitHub Actions: run: vendor/bin/coverage-guard check clover.xml) to block merging on insufficient coverage of critical paths.
• Rule customization: Extend EnforceCoverageForMethodsRule or implement CoverageRule to target specific patterns (e.g., controllers, facades, or methods with custom attributes like #[NoCoverageAllowed]).
• Parallel coverage merging: Use vendor/bin/coverage-guard merge coverage/*.xml > merged.xml to combine coverage from parallel test jobs (e.g., via phpunit-parallel-job-balancer) before enforcement.
• Patch coverage reporting: Run vendor/bin/coverage-guard patch-coverage clover.xml --patch changes.patch to output a coverage % for changed lines, compatible with GitLab’s coverage: pattern for MR visuals.

Gotchas and Tips

• Path mapping matters: Use addCoveragePathMapping() to normalize paths (e.g., /ci/path → __DIR__) when reusing clover.xml across environments—critical for --patch to match file paths correctly.
• Patch files must be clean: Ensure --patch uses relative paths (e.g., git diff master...HEAD > patch), not absolute or --full-index diffs—otherwise path matching fails silently.
• XML format choice: Prefer clover.xml over cobertura or php—smaller, IDE-friendly, and robust for GitLab + PhpStorm integration.
• Performance tip: When using PCOV, set XDEBUG_MODE=coverage anyway—this package relies on PHPUnit’s coverage collection, not Xdebug-specific features.
• IDE clickable links: Configure setEditorUrl() with your IDE template (e.g., phpstorm://open?file={file}&line={line}) for instant navigation from violations.
• Config autodetection caveats: Git root is auto-detected only if cwd is in a repo root; otherwise, explicitly call setGitRoot() to avoid patch mismatch errors.