@codeCoverageIgnore gezielt einsetzen, statt Coverage zu verfaelschen

1. Was @codeCoverageIgnore technisch bewirkt

Code Coverage misst, welcher Anteil des Produktivcodes waehrend eines Testlaufs tatsaechlich ausgefuehrt wurde, meist auf Zeilen-, Zweig- oder Methodenebene. Die Annotation @codeCoverageIgnore, gesetzt ueber einer einzelnen Methode, einer Klasse oder einem einzelnen Codeblock, weist den Coverage-Treiber an, die betroffenen Zeilen bei der Berechnung komplett zu uebergehen, als waeren sie gar nicht vorhanden. Weder ihre Ausfuehrung noch ihr Fehlen fliesst dann in die berichtete Prozentzahl ein.

Das unterscheidet @codeCoverageIgnore fundamental von einem einfach nicht getesteten Codeblock: Ungetesteter Code senkt die Coverage-Zahl und macht die Luecke sichtbar, ignorierter Code verschwindet stattdessen komplett aus der Statistik, so als haette er nie existiert. Genau diese Eigenschaft macht die Annotation gleichzeitig nuetzlich fuer echte Grenzfaelle und gefaehrlich, wenn sie unreflektiert eingesetzt wird, um eine Zahl kuenstlich in die Hoehe zu treiben.

2. Legitimer Einsatz: Triviale Getter und Setter

Der haeufigste und am wenigsten umstrittene Einsatzfall fuer @codeCoverageIgnore sind Getter und Setter, die tatsaechlich nichts weiter tun, als einen Wert unveraendert zurueckzugeben oder unveraendert zu speichern. Solcher Code enthaelt keine Logik, die fehlschlagen koennte, sodass ein dedizierter Test dafuer im Grunde nur die Sprache PHP selbst testet, nicht die eigene Fachlogik. In vielen Projekten wird deshalb bewusst darauf verzichtet, jeden einzelnen dieser Getter separat zu testen.

Wichtig ist die Einschraenkung wirklich trivial: Sobald ein Getter zusaetzliche Logik enthaelt, etwa eine Typumwandlung, eine Berechnung oder eine bedingte Rueckgabe je nach internem Zustand, handelt es sich nicht mehr um den trivialen Fall und die Ignorierung ist nicht mehr gerechtfertigt. Die Grenze liegt klar bei jeglicher Verzweigung oder Berechnung im Methodenkoerper, alles darueber hinaus verdient einen echten Test.

final class Money
{
    public function __construct(
        private readonly int $amountInCents,
        private readonly string $currency,
    ) {
    }

    /**
     * @codeCoverageIgnore
     */
    public function getAmountInCents(): int
    {
        return $this->amountInCents;
    }

    /**
     * @codeCoverageIgnore
     */
    public function getCurrency(): string
    {
        return $this->currency;
    }

    // Enthaelt Logik, also KEIN codeCoverageIgnore, sondern ein echter Test.
    public function format(): string
    {
        $euros = number_format($this->amountInCents / 100, 2, ',', '.');

        return match ($this->currency) {
            'EUR' => $euros . ' EUR',
            'USD' => '$' . $euros,
            default => $euros . ' ' . $this->currency,
        };
    }
}

3. Legitimer Einsatz: Unerreichbarer Defensive Code

Ein zweiter legitimer Fall ist Defensive Code, der aus gutem Grund existiert, aber unter normalen Umstaenden tatsaechlich nie erreicht werden kann, etwa eine default-Klausel in einem match-Ausdruck, die eine Exception wirft, obwohl alle bekannten Faelle bereits durch die vorherigen Zweige abgedeckt sind. Dieser Code dient als Absicherung gegen zukuenftige Aenderungen, etwa eine neue Enum-Variante, die vergessen wird zu behandeln, nicht als aktiv genutzter Pfad im heutigen Programm.

Auch hier gilt eine wichtige Einschraenkung: Die Ignorierung ist nur gerechtfertigt, wenn der Pfad tatsaechlich unerreichbar ist, nicht wenn er nur schwer zu erreichen ist. Ein Fehlerpfad, der etwa nur bei einem seltenen, aber durchaus moeglichen Netzwerkfehler ausgeloest wird, ist erreichbar und sollte mit einem Mock simuliert und getestet werden, statt vorschnell ignoriert zu werden, nur weil das Aufsetzen des Tests etwas Mehraufwand bedeutet.

enum ShippingMethod: string
{
    case Standard = 'standard';
    case Express = 'express';
    case PickupInStore = 'pickup';
}

final class ShippingCostCalculator
{
    public function calculate(ShippingMethod $method, int $weightInGrams): int
    {
        return match ($method) {
            ShippingMethod::Standard => 499,
            ShippingMethod::Express => 999,
            ShippingMethod::PickupInStore => 0,
            // @codeCoverageIgnoreStart
            // Absicherung gegen kuenftige Enum-Varianten, die hier vergessen
            // werden zu behandeln. Mit den aktuellen drei Faellen unerreichbar.
            default => throw new \LogicException('Unhandled shipping method'),
            // @codeCoverageIgnoreEnd
        };
    }
}

4. Grenzfaelle, bei denen Vorsicht geboten ist

Zwischen den eindeutig legitimen und den eindeutig problematischen Faellen liegt eine Grauzone, die besondere Aufmerksamkeit verdient. Ein Beispiel ist Code, der auf eine externe Systemzeit oder Zufallszahlen zugreift: Statt einen entsprechenden Zweig mit @codeCoverageIgnore zu uebergehen, laesst sich die Zeit oder der Zufallsgenerator fast immer ueber eine injizierbare Abstraktion kontrollieren und damit doch testen, wenn auch mit etwas mehr Aufwand als ein triviales Beispiel.

Ein weiterer Grenzfall ist Code fuer sehr seltene, aber grundsaetzlich reproduzierbare Fehlerzustaende, etwa eine Datenbankverbindung, die waehrend einer Transaktion abbricht. Solcher Code laesst sich mit einem gemockten Repository, das gezielt eine Exception wirft, durchaus testen. Die Versuchung, ihn stattdessen zu ignorieren, weil das Testsetup aufwendiger ist als bei einem einfachen Unit-Test, sollte einem Team bewusst sein und aktiv hinterfragt werden.

5. Ausschluss auf Verzeichnisebene als Alternative zu @codeCoverageIgnore

Fuer ganze Kategorien von Code, die grundsaetzlich nie sinnvoll durch Unit-Tests abgedeckt werden, etwa automatisch generierte Migrationsdateien oder reine DTO-Klassen ohne jede Logik, ist @codeCoverageIgnore an jeder einzelnen Stelle der falsche Hebel. Hier bietet sich stattdessen ein Ausschluss auf Verzeichnisebene in der phpunit.xml an, ueber den source-Block mit exclude, der ganze Ordner von vornherein aus der Coverage-Berechnung heraushaelt, ohne dass jede einzelne Datei manuell markiert werden muss.

Dieser Ansatz ist transparenter als viele verstreute @codeCoverageIgnore-Annotationen, weil die Ausnahme an einer zentralen, gut sichtbaren Stelle in der Konfiguration steht statt ueber Dutzende Dateien verteilt zu sein. Wichtig bleibt auch hier die gleiche Disziplin: Nur Verzeichnisse ausschliessen, die tatsaechlich keine testenswerte Logik enthalten, nicht Verzeichnisse, die lediglich unbequem zu testen sind.

<!-- phpunit.xml -->
<phpunit bootstrap="vendor/autoload.php">
    <source>
        <include>
            <directory>src</directory>
        </include>
        <exclude>
            <directory>src/Migrations</directory>
            <directory>src/Generated</directory>
        </exclude>
    </source>
</phpunit>

6. Die Gefahr der Coverage-Schoenfaerberei

Der eigentliche Risikofaktor bei @codeCoverageIgnore entsteht, wenn die Annotation nicht aus fachlicher Ueberlegung heraus gesetzt wird, sondern als schneller Weg, eine Coverage-Zahl zu erhoehen, etwa weil ein Team-Ziel von 90 Prozent Coverage naeher rueckt und schwer testbarer, aber durchaus testenswerter Code einfach ausgeblendet wird. Dieses Vorgehen erzeugt eine Zahl, die formal beeindruckend aussieht, aber immer weniger ueber die tatsaechliche Testabdeckung aussagt.

Besonders tueckisch ist, dass diese Verfaelschung sich selbst verstaerkt: Sobald ein Team gelernt hat, dass @codeCoverageIgnore ein bequemer Weg ist, unangenehme Luecken verschwinden zu lassen, wird die Annotation beim naechsten schwierigen Testfall noch schneller gegriffen, weil der Weg des geringsten Widerstands bereits etabliert ist. Am Ende steht eine Codebasis mit hoher berichteter Coverage, aber vielen tatsaechlich ungetesteten, kritischen Pfaden, die niemand mehr als Luecke wahrnimmt.

7. Code Review als Kontrollinstanz

Weil @codeCoverageIgnore so leicht missbraucht werden kann, sollte jeder neu eingefuegte Einsatz der Annotation im Code Review explizit thematisiert werden, aehnlich wie ein @phpstan-ignore-next-line oder ein try/catch mit leerem catch-Block. Ein Reviewer sollte gezielt nachfragen, warum der betroffene Code nicht testbar ist, und pruefen, ob eine der beiden legitimen Kategorien, trivialer Getter/Setter oder tatsaechlich unerreichbarer Defensive Code, wirklich zutrifft.

Ein einfaches, aber wirksames Mittel ist, jede @codeCoverageIgnore-Annotation mit einer kurzen Begruendung im selben Kommentarblock zu verpflichten, wie es im Beispiel des Shipping-Calculators oben bereits gezeigt wurde. Diese Begruendung zwingt den Autor, sich die Rechtfertigung selbst noch einmal bewusst zu machen, und gibt jedem spaeteren Leser sofort Kontext, ohne dass er die Historie des Codes recherchieren muss.

final class LegacyPriceFormatter
{
    public function format(mixed $rawPrice): string
    {
        if (!is_numeric($rawPrice)) {
            // @codeCoverageIgnoreStart
            // Absicherung fuer Legacy-Aufrufer aus dem alten ERP-Export.
            // In allen bekannten Aufrufpfaden ist $rawPrice bereits numerisch,
            // der Import-Prozess (siehe Ticket ERP-204) garantiert das seit 2024.
            throw new \InvalidArgumentException('Price must be numeric');
            // @codeCoverageIgnoreEnd
        }

        return number_format((float) $rawPrice, 2, ',', '.') . ' EUR';
    }
}

8. Coverage-Ziele mit Bedacht formulieren

Ein Grossteil des Missbrauchs von @codeCoverageIgnore laesst sich indirekt vermeiden, indem Coverage-Ziele im Team von vornherein realistisch und differenziert formuliert werden. Ein pauschales Ziel von 100 Prozent Coverage ueber die gesamte Codebasis erzeugt fast zwangslaeufig Druck, Grenzfaelle grosszuegig zu ignorieren, weil manche Codepfade tatsaechlich unpraktisch bis unmoeglich vollstaendig zu erreichen sind. Ein realistischeres Ziel liegt meist zwischen 80 und 95 Prozent, je nach Codebasis, mit klar dokumentierten Ausnahmen fuer generierten Code oder reine Wertobjekte.

Zusaetzlich hilft es, Coverage nicht als reines Prozent-Ziel, sondern im Zusammenspiel mit der Anzahl aktiver @codeCoverageIgnore-Vorkommen zu betrachten. Ein Team, das beide Zahlen gemeinsam beobachtet, etwa ueber ein einfaches Grep-Skript in der CI-Pipeline, das die Ignore-Vorkommen zaehlt und bei einem ploetzlichen Anstieg warnt, erkennt Schoenfaerberei deutlich frueher als ein Team, das nur auf die reine Prozentzahl schaut.

#!/usr/bin/env bash
# ci/check-coverage-ignore-count.sh
# Warnt, wenn die Anzahl der codeCoverageIgnore-Vorkommen sprunghaft steigt.

set -euo pipefail

CURRENT_COUNT=$(grep -r "@codeCoverageIgnore" --include="*.php" src/ | wc -l)
BASELINE_COUNT=$(cat ci/coverage-ignore-baseline.txt)

if [ "$CURRENT_COUNT" -gt "$((BASELINE_COUNT + 5))" ]; then
    echo "Warnung: codeCoverageIgnore-Vorkommen von $BASELINE_COUNT auf $CURRENT_COUNT gestiegen."
    echo "Bitte im Review pruefen, ob jede neue Ignorierung wirklich gerechtfertigt ist."
    exit 1
fi

echo "OK: $CURRENT_COUNT codeCoverageIgnore-Vorkommen (Baseline: $BASELINE_COUNT)."

9. Team-Richtlinien fuer den Einsatz von @codeCoverageIgnore

Damit @codeCoverageIgnore dauerhaft ein praezises statt ein missbrauchtes Werkzeug bleibt, braucht ein Team eine kurze, schriftlich festgehaltene Richtlinie mit den zulaessigen Kategorien, etwa genau die beiden in diesem Artikel beschriebenen: triviale Getter/Setter ohne jede Logik und tatsaechlich unerreichbarer Defensive Code. Alles ausserhalb dieser Kategorien sollte im Review kritisch hinterfragt werden, bevor die Annotation akzeptiert wird.

Ergaenzend lohnt sich eine periodische Durchsicht aller bestehenden @codeCoverageIgnore-Vorkommen im Projekt, etwa halbjaehrlich, um zu pruefen, ob sich seither an den betroffenen Codestellen etwas geaendert hat, das die Ignorierung nicht mehr rechtfertigt, etwa weil ein frueher unerreichbarer Zweig durch eine neue Anforderung nun doch erreichbar geworden ist. Die folgende Tabelle fasst die wichtigsten Kategorien und ihre Bewertung zusammen.

10. Zusammenfassung

11. FAQ: @codeCoverageIgnore in PHPUnit: Das Wichtigste auf einen Blick