Covers Validator Laravel Package

Getting Started

This package enforces that PHPUnit test methods have valid @covers annotations—crucial for maintaining high-quality code coverage reports and catching misconfigured tests. Begin by installing via Composer: composer require --dev ockcyp/covers-validator. Next, run it using the CLI tool it provides (typically vendor/bin/covers-validator), which scans your test suite for improperly formatted or invalid @covers tags. Your first use case: catching accidental omissions like @covers ::publicMethod instead of @covers ::publicMethod(), or referencing non-existent classes/methods.

Implementation Patterns

Integrate it into your CI pipeline (e.g., GitHub Actions, GitLab CI) as a pre-commit or merge-request gate. Configure it via a covers-validator.yml or .covers-validator.php config file to exclude vendor directories, define allowed annotation patterns, or set strictness levels (e.g., require full method signatures vs. class-only). Use it alongside coverage tools like phpunit --coverage-text to ensure tests not only run but accurately declare what they cover—ideal for teams aiming for 100% meaningful coverage without false positives from over-covetous annotations.

Gotchas and Tips

Be aware: it expects strict PSR-12–compliant PHPDoc, so trailing slashes or spacing variations (e.g., @coversClass Foo\Bar vs @covers Foo\Bar) may fail unpredictably—always check config for custom regex overrides. Its validation is syntactic and not reflective—you won’t detect static call mismatches like @covers Foo::bar vs actual Foo::Bar() (case sensitivity matters). Extend it via custom validators (if the API supports it) or use its exit codes (0 = clean, 1 = missing/invalid tags) in scripts. If tests use @coversNothing or dynamic mocking, ensure your config excludes those unless you want strict enforcement.