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

By Daniel Zoghalchali·Latchkey

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.

Diagnose it: version, extensions, limits

Terminal

php -v && php -m | head -30
php -i | grep -E "memory_limit|max_execution_time"
composer check-platform-reqs 2>/dev/null

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.

Frequently asked questions

What causes PHPUnit "No code coverage driver available"?

There are 2 common causes: no coverage driver enabled on the runner and xdebug present but not in coverage mode. A minimal PHP image ships neither pcov nor Xdebug.

How do I fix PHPUnit "No code coverage driver available"?

There are 3 fixes depending on which cause you have: enable a coverage driver in ci, put xdebug in coverage mode, and confirm the driver is active. Work through them in order, since the first is the most common.

What does PHPUnit "No code coverage driver available" actually mean?

PHPUnit aborts a coverage run with "No code coverage driver is available", or "Neither … pcov nor … Xdebug … is available".

How do I stop PHPUnit "No code coverage driver available" happening again?

Enable pcov (or Xdebug coverage mode) in any CI job that collects coverage. The prevention section lists 3 changes that keep it from recurring.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.