Jak wygenerować raport pokrycia kodu w PHPUnit krok po kroku

Po poznaniu podstaw pokrycia kodu, czas przejść do konkretów. W tym artykule pokażę Ci dokładnie, jak skonfigurować środowisko PHP do generowania raportu pokrycia kodu przy pomocy PHPUnit. Będzie to kompleksowy poradnik – od instalacji rozszerzeń, przez konfigurację phpunit.xml, aż po interpretację wyników raportu HTML.

Krok 1: Wybór narzędzia do zbierania danych o pokryciu

PHP jako język nie posiada wbudowanego mechanizmu śledzenia pokrycia kodu, dlatego potrzebujemy zewnętrznych rozszerzeń. Do wyboru mamy dwa:

Xdebug – popularne narzędzie debugujące z opcją zbierania danych o pokryciu kodu. Działa wolniej, ale daje szczegółowe informacje.
PCOV – lekkie rozszerzenie stworzone specjalnie pod pokrycie kodu. Jest szybsze, ale nie obsługuje wszystkich zaawansowanych opcji debugowania.

Aby sprawdzić, czy masz któreś z nich zainstalowane, użyj:

php -m | grep -E "xdebug|pcov"

Jeśli nie, zainstaluj jedno z nich przez pecl:

pecl install xdebug

lub dla PCOV:

pecl install pcov

Krok 2: Konfiguracja rozszerzenia

Dla Xdebuga musisz ustawić tryb pokrycia:

; w php.ini lub .ini pliku konfigurującym CLI
xdebug.mode=coverage

Dla PCOV:

pcov.enabled=1
pcov.directory=.

W przypadku Dockera warto dopisać te opcje bezpośrednio do kontenera CLI lub PHP-FPM.

Krok 3: Przygotowanie PHPUnit

Upewnij się, że masz zainstalowanego PHPUnit. W nowoczesnych projektach najlepiej zainstalować go lokalnie przez Composer:

composer require --dev phpunit/phpunit

Stwórz plik phpunit.xml w katalogu głównym projektu z następującą konfiguracją:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="vendor/autoload.php"
         colors="true"
         verbose="true">

    <coverage processUncoveredFiles="true">
        <include>
            <directory suffix=".php">src</directory>
        </include>
        <report>
            <html outputDirectory="coverage-report"/>
        </report>
    </coverage>

</phpunit>

To zapewni, że raport HTML zostanie wygenerowany w katalogu coverage-report/ i będzie zawierał analizę plików z katalogu src.

Krok 4: Uruchomienie testów z pokryciem

Uruchom PHPUnit z włączonym pokryciem kodu:

XDEBUG_MODE=coverage ./vendor/bin/phpunit --coverage-html=coverage-report

Jeśli używasz PCOV:

php -dpcov.enabled=1 ./vendor/bin/phpunit --coverage-html=coverage-report

W zależności od rozmiaru projektu, testy mogą potrwać kilka lub kilkanaście sekund.

Krok 5: Przeglądanie raportu HTML

Po zakończeniu testów otwórz plik coverage-report/index.html w przeglądarce.

Zobaczysz:

Tabelę z listą plików PHP oraz procentowym pokryciem każdej klasy.
Zielone linie – kod, który został wykonany.
Czerwone linie – kod, który nie został uruchomiony.
Żółte linie – fragmenty częściowo pokryte (np. warunek if, w którym przeszliśmy tylko jedną z gałęzi).

Raport zawiera także metrykę CRAP (Change Risk Anti-Patterns), która łączy złożoność cyklomatyczną i pokrycie, by ocenić, jak ryzykowna w modyfikacji jest dana funkcja.

Krok 6: Najczęstsze problemy

Brak danych o pokryciu: Upewnij się, że xdebug.mode=coverage jest aktywne. W przypadku PCOV sprawdź pcov.directory.
PHPUnit zgłasza brak wsparcia dla pokrycia: Sprawdź, czy używasz kompatybilnej wersji PHP i PHPUnit. Od wersji 10.x PHPUnit wymaga PCOV 1.0+ lub Xdebug 3.0+.
Raport nie zawiera niektórych plików: Upewnij się, że directory w <include> wskazuje na katalog z klasami, które mają być analizowane.

Podsumowanie

Wygenerowanie raportu pokrycia kodu to proces jednorazowy, który znacząco zwiększa świadomość jakości Twojego projektu. Dzięki takim raportom:

szybciej zidentyfikujesz luki w testach,
ocenisz, które części kodu warto przetestować lepiej,
będziesz pewniejszy przy refaktoryzacji i wdrażaniu zmian.

Jak wygenerować raport pokrycia kodu w PHPUnit krok po kroku