Coverage Reports and Thresholds

You type the command every tutorial shows:

vendor/bin/phpunit --coverage-text

and PHPUnit prints Warning: No code coverage driver available before running your tests with no report at all. The runner does not collect coverage itself — the php-code-coverage library does, and it needs an extension in the PHP process that instruments opcodes. You have two realistic choices, and they are not equivalent.

Xdebug is the debugger you probably already have installed, and it only collects coverage when its coverage mode is on:

# per-run, without editing php.ini
XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text
# or persist it: xdebug.mode=coverage in php.ini

PCOV (pecl install pcov) exists only to collect coverage — no debugger, no trace, far less overhead. The difference is measurable. On a 2,804-test suite with PHPUnit 10:

PCOV costs roughly 1.5× the plain run; Xdebug line coverage about 2.2×; Xdebug with branch and path coverage about 20×. A second data point, from a Laravel framework run: 33 s with no coverage, 77 s with PCOV, 154 s with Xdebug. PCOV is consistently about twice as fast as Xdebug for the same line-level report.

Verify what your process actually has before blaming the configuration:

php -m | grep -E 'xdebug|pcov'              # is a driver loaded for the CLI at all?
php -r 'echo ini_get("xdebug.mode"), PHP_EOL;'   # off | develop | debug | coverage

Watch the SAPI while you are there: php -m reports the CLI's php.ini, which is the only interpreter PHPUnit uses, but many machines carry a separate php-fpm.ini for the web server. An extension visible in a browser request can be invisible to your tests, and the reverse — a mismatch that looks like a PHPUnit problem and is an installation problem.

Switching collection on for one job needs no image change at all:

- name: Tests with coverage
  run: vendor/bin/phpunit --coverage-clover build/coverage.xml
  env:
    XDEBUG_MODE: coverage

An Xdebug left in develop or debug mode taxes every run whether or not you asked for coverage, so keep it off for daily work and switch it on only for the job that publishes a report.

The trade-off is one line: PCOV collects line coverage only — branch and path coverage require Xdebug (with --branch-coverage / --path-coverage on PHPUnit versions that support them). If your team's gate is a line-percentage and CI minutes cost money, PCOV is the default. If you are investigating whether both arms of a condition are exercised, Xdebug is the only way to see it — and you now know why that job belongs in a scheduled CI run, not in your inner loop.

Two operational habits follow from the table:

• Daily runs stay driver-free. vendor/bin/phpunit --testsuite unit with Xdebug loaded but xdebug.mode=off is the fast path; toggling coverage on for every local run turns a 22-second suite into a 50-second one, which is how teams quietly stop running tests.

Notice how this composes with Mocking Dependencies: mocking already stripped network latency out of the suite, and the coverage driver puts a multiplier back on top of whatever is left. The two costs together — execution and instrumentation — decide whether your inner loop stays near a second or drifts past a minute, which is exactly why drivers are toggled per run instead of left on.

• Coverage runs are deliberate. CI job, nightly job, or a pre-merge check — one of them, on one machine, with the driver enabled for that invocation only.

With a driver active, the report still depends on a setting that decides what is being measured at all.

--coverage-text gives you one number. The HTML report tells you where to work:

vendor/bin/phpunit --coverage-html build/coverage --coverage-text
open build/coverage/index.html

The index lists every file you declared as source, its class/method/line percentages, and — when you open a file — the actual source with unexecuted lines highlighted in red. That red is the report's only real content: the number is a summary, the red lines are the worklist.

Which files appear is decided once, in phpunit.xml:

<source>
  <include>
    <directory suffix=".php">src</directory>
  </include>
  <exclude>
    <directory>src/Migrations</directory>
    <directory>src/Generated</directory>
  </exclude>
</source>

<coverage>
  <report>
    <html outputDirectory="build/coverage"/>
    <clover outputFile="build/coverage.xml"/>
    <text outputFile="php://stdout" showUncoveredFiles="true"/>
  </report>
</coverage>

The split trips everyone once: <source> answers "what is my code", <coverage> answers "which report files to write". If you skip <source>, there is nothing to measure and you pass --coverage-filter src on the command line instead.

There is a stricter mode worth knowing, because it changes what the number means. Declare intent on the test class:

#[CoversClass(TaxCalculator::class)]
final class TaxCalculatorTest extends TestCase
{
    // ...
}

and set requireCoverageMetadata="true" in phpunit.xml. Now lines executed by a test that never declared TaxCalculator do not count toward TaxCalculator — the percentage reflects what your tests claim responsibility for, and any test without metadata is flagged. It is extra ceremony, and teams usually adopt it together with the threshold enforcement in the next chapter.

Output files land wherever outputDirectory says, so put build/ in .gitignore and, in CI, publish the HTML as a build artifact: a reviewer who can click the red line in a pull request fixes the gap without checking anything out locally.

Guard the denominator, because the percentage is only ever as honest as the file set behind it:

Then read the red lines as untested branches, not untested files:

public function totalWithTax(float $rate): int
{
    if ($rate < 0) {
        throw new InvalidArgumentException('rate must be >= 0');   // red: guard never ran
    }

    $total = (int) round($this->subtotal * (1 + $rate));
    return $total ?? 0;                                             // red: fallback never needed
}

A red guard clause means no test ever sent a negative rate — the error path that fails only in production. A red ?? 0 means the fallback is unproven. Paying lines that execute the happy path but skip every validation, recovery, and boundary branch is exactly how a suite reports 90% while the features nobody tested keep breaking.

Work the report in file order, not percentage order. A file at 60% with three red guard clauses is a day of focused work; a file at 45% that is one large match over a constant mapping table may be correct to leave alone. The summary lists classes, methods, and lines separately and they routinely disagree — trust the lines, because they are the ones rendered beside the actual source. When a file reads 100% and you still do not trust it, that unease is justified: nothing in this report measures whether an assertion exists.

For CI and third-party services, --coverage-clover build/coverage.xml writes machine-readable XML — a <metrics> element with statements and coveredstatements — consumed by SonarQube, Codecov, and Coveralls, and by the gate you are about to build in the next chapter.

One known honesty limit worth mentioning in an interview: coverage is collected at the opcode level, so match expression arms can be reported as covered even when only one arm ran. Line coverage is an approximation of execution, not proof of anything — which is the argument for the threshold and mutation work ahead.

A coverage report nobody enforces is a report nobody maintains. PHPUnit will print the percentage; it has no built-in minimum, so the gate is yours to build, and it takes five lines.

vendor/bin/phpunit --coverage-clover build/coverage.xml
php -r '
$x = simplexml_load_file("build/coverage.xml");
$m = $x->project->metrics;
$p = 100 * (float) $m["coveredstatements"] / (float) $m["statements"];
printf("coverage: %.1f%%\n", $p);
exit($p >= 80.0 ? 0 : 1);
'

Non-zero exit fails the job. Two design rules make this a gate instead of a nuisance:

• Fail down, never re-ratchet up automatically. The threshold is a floor written by the team; a script that recomputes the floor from the current number protects nothing.
• Exclude what you deliberately do not count in <source>, so the gate cannot be satisfied by deleting tests from tests/ while the denominator quietly shrinks.

The deeper problem is that coverage measures execution, not verification. A line is "covered" the moment any test passes through it — even if the test asserts nothing about what happened:

if ($rate >= 0.0) {        // mutant: if ($rate > 0.0)  — survives a weak suite
    $total = round($base * (1 + $rate));
}

Your suite can execute that line 50 times and still not notice that a zero rate is now rejected, because no test asserts the boundary. Mutation testing closes the gap: Infection rewrites your source — >= becomes >, && becomes ||, an increment disappears — runs the suite against each mutant, and reports every mutant your tests failed to kill.

composer require --dev infection/infection
vendor/bin/infection --threads=4 --min-msi=80 --min-covered-msi=90

Both flags fail the build when the score drops, which is the same ratchet philosophy as the coverage floor — applied to a number that actually measures whether your assertions assert something. Infection reuses your coverage data to mutate only covered code, which is why the PCOV/Xdebug decision from the first chapter has a direct effect on how long a mutation run takes: it runs your suite many times over.

Put the gate in the repository so it cannot be forgotten in someone's local override:

// infection.json5
{
  "source": { "directories": ["src"] },
  "minMsi": 80,
  "minCoveredMsi": 90,
  "timeout": 10
}

Cost then decides how you schedule it. Infection re-runs your suite once per mutant — hundreds of runs on a real codebase — so on a pull request you mutate only what changed:

vendor/bin/infection --threads=max --git-diff-lines --min-msi=80

--git-diff-lines restricts mutants to the lines your branch touched, turning a twenty-minute full run into a two-minute check on the files in the diff; the complete run then lives in a nightly job. The timeout key marks pathologically slow mutants as escaped instead of letting one hang the build, and every escaped mutant is printed with a diff so a reviewer can judge it — the loop that actually improves the suite, because each survivor is either a missing assertion or the next test worth writing.

Enforced in CI, the combination reads well in a review and better in an interview: coverage tells you what was touched, mutation tells you what would have broken, and the threshold stops either from quietly rotting. The phase's tooling ends here — Creating a Laravel Project moves from a bare PHPUnit setup to a framework that ships its own test harness, factories, and fakes built on everything you have just configured.