PHPUnit "No code coverage driver available" - Install pcov or Xdebug

PHPUnit can only collect code coverage when a coverage driver is loaded - either pcov or Xdebug (in coverage mode). On a runner with neither, any coverage-producing run errors out instead of generating a report.

What this error means

PHPUnit aborts a coverage run with "No code coverage driver is available", or "Neither … pcov nor … Xdebug … is available". A plain test run (no --coverage-*) passes; only coverage fails.

PHPUnit output

$ vendor/bin/phpunit --coverage-clover coverage.xml
No code coverage driver is available.
Make sure that pcov or Xdebug is installed and enabled.

Common causes

No coverage driver enabled on the runner

A minimal PHP image ships neither pcov nor Xdebug. PHPUnit has nothing to instrument lines with, so coverage cannot be produced.

Xdebug present but not in coverage mode

Xdebug 3 only records coverage when xdebug.mode includes coverage. With xdebug.mode=off|debug it is loaded but unusable for coverage.

How to fix it

Enable a coverage driver in CI

pcov is fast and coverage-only; setup-php can enable it via coverage:.

.github/workflows/ci.yml

- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
    coverage: pcov   # or xdebug

Put Xdebug in coverage mode

If using Xdebug, set its mode so it can record coverage.

Terminal

XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-clover coverage.xml

Confirm the driver is active

Run php -m | grep -E 'pcov|xdebug' to confirm it is loaded.
For Xdebug, check php -i | grep xdebug.mode includes coverage.
Prefer pcov for speed unless you also need Xdebug’s step debugger.

How to prevent it

Enable pcov (or Xdebug coverage mode) in any CI job that collects coverage.
Prefer pcov for coverage-only runs; it is much faster than Xdebug.
Keep coverage jobs separate so non-coverage runs stay fast.