Cobertura de código en PHP: métricas, herramientas y trucos

La paradoja del tester: el 100% de cobertura no es una panacea

Los desarrolladores se dividen en dos bandos: los que escriben pruebas «por cumplir» y los que persiguen el ansiado 100% de cobertura de código. La verdad, como siempre, está en el medio. En este artículo analizaremos qué es la cobertura de código en PHP, qué métricas son realmente importantes y cuáles pueden ser engañosas. Aprenderás cómo usar PHPUnit, Xdebug e Infection para convertir las pruebas de una rutina tediosa en una poderosa herramienta de control de calidad.

Pongámonos de acuerdo desde ya: este artículo no trata sobre «cómo escribir una prueba», sino sobre cómo entender si tus pruebas realmente funcionan. Hablaremos en el lenguaje de los números, las métricas y los ejemplos prácticos. Si programas en PHP y quieres que tu código no se rompa ante el primer cambio, has llegado al lugar indicado.

¿Qué es realmente la cobertura de código (Code Coverage)?

La cobertura de código es una métrica que indica qué porcentaje del código fuente se ejecuta durante la ejecución de las pruebas. Suena simple, pero detrás de este número se esconden diferentes niveles de análisis:

\n
• Cobertura de líneas (Line Coverage) — la métrica más básica. Cuántas líneas de código son «tocadas» por las pruebas.
\n
• Cobertura de ramas (Branch Coverage) — verifica si se han ejecutado todas las ramas posibles de las condiciones (if/else, switch).
\n
• Cobertura de rutas (Path Coverage) — la métrica más compleja. Verifica todas las rutas posibles de ejecución del código.
\n
• Cobertura de funciones/métodos — cuántas funciones han sido invocadas al menos una vez.
\n

Para un desarrollador PHP, el estándar de oro es la cobertura de líneas + ramas. Pero recuerda: un 80% de cobertura de líneas puede ocultar un 40% de ramas no verificadas. El código puede «ejecutarse», pero la lógica puede no estar probada.

¿Por qué el 100% de cobertura es una trampa?

Imagina una función que procesa pagos:

<?php\n\nfunction processPayment(float $amount, string $currency): bool {\n    if ($amount <= 0) {\n        throw new InvalidArgumentException('El monto debe ser positivo');\n    }\n    \n    $rate = getRate($currency); // API externa\n    $converted = $amount * $rate;\n    \n    if ($converted > 10000) {\n        return false; // requiere confirmación\n    }\n    \n    return saveTransaction($converted); // escritura en BD\n}\n

Una prueba que solo verifica el escenario exitoso (monto > 0, moneda USD, conversión < 10000) te dará un 100% de cobertura de líneas. Pero no probará ni la excepción ni el caso de un pago grande. Conclusión: la cantidad de líneas cubiertas no equivale a la calidad de las pruebas.

Herramientas para medir la cobertura en PHP

El ecosistema PHP ofrece varias herramientas potentes. Veamos tres principales: Xdebug, PCOV y PHPUnit con soporte integrado de cobertura.

Xdebug: el veterano con amplias capacidades

Xdebug es el depurador y perfilador más popular para PHP. Puede recopilar datos de cobertura de código. La instalación es estándar:

# Instalación con pecl\npecl install xdebug\n\n# O con Docker\nRUN pecl install xdebug && docker-php-ext-enable xdebug\n

En php.ini debes activar el modo de cobertura:

xdebug.mode=coverage\n

Ejecución con PHPUnit:

./vendor/bin/phpunit --coverage-html ./reports/coverage\n

Ventajas de Xdebug: precisión, soporte de ramas, integración con CI/CD. Desventajas: ralentiza la ejecución de las pruebas entre 3 y 5 veces. Para proyectos grandes, esto es crítico.

PCOV: rápido y ligero

PCOV (PHP Code Coverage) es una alternativa a Xdebug, creada específicamente para recopilar cobertura. No ralentiza la ejecución porque no incluye un depurador.

pecl install pcov\n\n# Activación en php.ini\nextension=pcov.so\npcov.enabled=1\n

Ejecución