Named Datasets in Data Providern: lesbare Testausgaben in PHPUnit

1. Warum die Standard-Testausgabe bei Data Providern unbrauchbar ist

PHPUnits Data Provider sind ein mächtiges Werkzeug, um eine Testmethode mit vielen verschiedenen Eingaben laufen zu lassen, ohne die Testlogik zu duplizieren. Der Standardfall sieht dabei so aus, dass der Data Provider ein einfaches Array von Arrays zurückgibt, jeder innere Eintrag ein Satz Argumente für die Testmethode. PHPUnit nummeriert diese Einträge automatisch durch, und genau das wird bei einem Fehlschlag zum Problem.

Meldet PHPUnit 'testCalculatesTax with data set #4 failed', muss zunächst der Data Provider geöffnet, der vierte Eintrag gezählt und interpretiert werden, was er eigentlich testen sollte. Bei einem Data Provider mit zwanzig Einträgen und häufigen Änderungen an der Reihenfolge ist das nicht nur lästig, sondern eine echte Fehlerquelle: Die Nummer #4 von heute ist morgen vielleicht #6, wenn jemand einen Eintrag vorne einfügt.

2. Das konkrete Problem an einem nummerierten Beispiel

Am deutlichsten wird das Problem an einem Data Provider für die Berechnung von Versandkosten mit mehreren Randfällen: Standardversand, kostenloser Versand ab einem Schwellenwert, internationale Zuschläge, negative Mengen als Fehlerfall. Ohne Benennung sind das schlicht Einträge null bis drei, und die Testausgabe bei einem Fehlschlag liefert keinerlei fachlichen Kontext, nur eine Zahl.

In der Praxis führt das dazu, dass Entwickler bei einem roten CI-Lauf zunächst minutenlang im Data-Provider-Code suchen, bevor sie überhaupt verstehen, welcher Fall gescheitert ist. Bei einer Testsuite mit hunderten solcher Provider summiert sich das zu spürbarem Zeitverlust, gerade in Situationen, in denen schnelle Diagnose am wichtigsten wäre, etwa direkt nach einem fehlgeschlagenen Deployment.

<?php

declare(strict_types=1);

namespace Mironsoft\Tests\Unit;

use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;

// Ohne Benennung: nummerierte Eintraege
final class ShippingCostUnnamedTest extends TestCase
{
    #[Test]
    #[DataProvider('provideCases')]
    public function berechnetVersandkosten(int $weightGrams, string $country, int $expectedCents): void
    {
        self::assertSame($expectedCents, (new ShippingCalculator())->calculate($weightGrams, $country));
    }

    public static function provideCases(): array
    {
        return [
            [500, 'DE', 490],
            [500, 'AT', 690],
            [10000, 'DE', 0],
            [-500, 'DE', 0],
        ];
    }
}

// Fehlermeldung bei Fehlschlag:
// ShippingCostUnnamedTest::berechnetVersandkosten with data set #2 failed

3. Die Lösung: assoziative Array-Keys als sprechende Namen

PHPUnit erlaubt es, statt eines numerischen Index einen String-Key für jeden Eintrag im Data Provider zu vergeben. Dieser String erscheint dann wortwörtlich in der Testausgabe, sowohl bei erfolgreichem als auch bei fehlgeschlagenem Testlauf. Der Umbau ist trivial, aus einem einfachen Array-Literal wird ein assoziatives Array mit beschreibenden Keys, an der Testmethode selbst ändert sich nichts.

Wichtig für gute Namen ist, den fachlichen Fall zu beschreiben, nicht die technischen Eingabewerte zu wiederholen. 'Standardversand Inland' ist besser als '500 Gramm DE', weil der Name die Testabsicht kommuniziert statt nur die Zahlen aus dem Array-Eintrag zu spiegeln, die man beim Lesen der Fehlermeldung ohnehin schon vermutet hätte.

<?php

declare(strict_types=1);

namespace Mironsoft\Tests\Unit;

use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;

// Mit benannten Datasets: sofort verstaendliche Testausgabe
final class ShippingCostNamedTest extends TestCase
{
    #[Test]
    #[DataProvider('provideCases')]
    public function berechnetVersandkosten(int $weightGrams, string $country, int $expectedCents): void
    {
        self::assertSame($expectedCents, (new ShippingCalculator())->calculate($weightGrams, $country));
    }

    public static function provideCases(): array
    {
        return [
            'Standardversand Inland' => [500, 'DE', 490],
            'Auslandszuschlag Oesterreich' => [500, 'AT', 690],
            'Kostenloser Versand ab Schwellenwert' => [10000, 'DE', 0],
            'Negatives Gewicht wird auf Null geklemmt' => [-500, 'DE', 0],
        ];
    }
}

// Fehlermeldung bei Fehlschlag:
// ShippingCostNamedTest::berechnetVersandkosten with data set
// "Kostenloser Versand ab Schwellenwert" failed

4. Named Datasets zum gezielten Filtern in der CLI nutzen

Ein oft übersehener Zusatznutzen benannter Datasets ist die Möglichkeit, einen einzelnen Fall gezielt per Kommandozeile auszuführen. Mit dem Filter-Argument --filter lässt sich der Testname inklusive Dataset-Bezeichnung als regulärer Ausdruck angeben, sodass genau ein fachlicher Fall isoliert läuft, ohne die gesamte restliche Suite abzuwarten.

Das beschleunigt vor allem die Fehlersuche bei einem einzelnen fehlgeschlagenen Fall erheblich: Statt die komplette Testklasse mit allen zwanzig Datasets erneut laufen zu lassen, wird gezielt nur 'Kostenloser Versand ab Schwellenwert' ausgeführt, was bei langsamen Integrationstests den Feedback-Zyklus von Minuten auf Sekunden verkürzen kann.

# Nur den Fall "Kostenloser Versand ab Schwellenwert" ausfuehren
vendor/bin/phpunit --filter "berechnetVersandkosten.*Kostenloser Versand"

# Alle Faelle einer Testmethode mit --testdox anzeigen,
# Named Datasets erscheinen als eigene Zeile im Report
vendor/bin/phpunit --testdox tests/Unit/ShippingCostNamedTest.php

5. Fallstricke: doppelte Keys, Sonderzeichen und lange Namen

Der häufigste Fehler ist ein doppelt vergebener Key innerhalb desselben Data Providers, PHP überschreibt in diesem Fall stillschweigend den vorherigen Eintrag mit demselben Array-Key, ohne Warnung. Das Ergebnis ist ein Data Provider, der scheinbar zehn Fälle enthält, tatsächlich aber nur neun ausführt, weil einer verlorengegangen ist, ein besonders tückischer stiller Datenverlust.

Ein zweites Problem sind Sonderzeichen in Namen, etwa Anführungszeichen oder Backslashes, die in der Kommandozeile beim Filtern escaped werden müssen und dort schnell für Verwirrung sorgen. Bewährt hat sich eine einfache Konvention: Namen bestehen nur aus Buchstaben, Ziffern, Leerzeichen und einfachen Satzzeichen wie Doppelpunkt oder Bindestrich, keine Anführungszeichen, keine Klammern, keine Sonderzeichen, die eine Shell fehlinterpretieren könnte.

<?php

declare(strict_types=1);

// FALSCH: doppelter Key ueberschreibt den ersten Eintrag stillschweigend
public static function provideBrokenCases(): array
{
    return [
        'Grenzfall Null' => [0, 0],
        'Grenzfall Null' => [0, 5],   // ueberschreibt den Eintrag oben!
    ];
}

// RICHTIG: eindeutige, beschreibende Keys ohne Sonderzeichen
public static function provideCases(): array
{
    return [
        'Grenzfall Menge Null' => [0, 0],
        'Grenzfall Preis Null bei positiver Menge' => [0, 5],
    ];
}

6. Eine Namenskonvention für das ganze Team etablieren

Named Datasets entfalten ihren vollen Nutzen erst, wenn das gesamte Team eine konsistente Namenskonvention verwendet. Bewährt hat sich das Muster 'Kontext: erwartetes Verhalten', etwa 'Rabattcode abgelaufen: keine Reduktion' oder 'Warenkorb leer: Fehler wird geworfen'. Diese Struktur macht auf einen Blick klar, welcher Zustand getestet wird und was PHPUnit dabei erwartet.

Ein PHPStorm-Live-Template oder eine kurze Team-Konvention im Onboarding-Dokument hilft, diese Struktur konsequent durchzuhalten. Wichtig ist außerdem, Named Datasets bei Code-Reviews genauso ernst zu nehmen wie Variablennamen, ein schlecht benannter Datenname ist letztlich derselbe Lesbarkeitsverlust wie eine schlecht benannte Variable, nur eben in der Testausgabe statt im Quellcode sichtbar.

7. Bestehende Data Provider ohne Benennung nachträglich umstellen

Bei einer gewachsenen Testsuite lohnt sich die Nachrüstung nicht überall gleichermaßen, priorisiert werden sollten Data Provider, deren Tests in der Vergangenheit häufig fehlschlugen oder die besonders viele Einträge enthalten. Ein einfacher Indikator dafür ist die Anzahl der Einträge im Array: Ab etwa fünf Einträgen wird die Nummerierung unübersichtlich genug, dass sich die Umbenennung praktisch immer lohnt.

Die Umstellung selbst ist risikoarm, weil sie an der Testlogik nichts ändert, ausschließlich die Array-Keys werden ergänzt. Ein guter Zwischenschritt ist, bei jeder ohnehin anstehenden Änderung an einer Testdatei die Data-Provider-Keys mit zu benennen, statt eine separate, große Umbau-Aktion für die gesamte Suite zu planen, die selten priorisiert wird.

8. Grenzen: wann Named Datasets nicht die richtige Lösung sind

Named Datasets sind kein Allheilmittel. Bei Data Providern mit sehr vielen automatisch generierten Einträgen, etwa allen Kombinationen aus zwei Enum-Werten, ist eine sprechende Benennung jedes einzelnen Falls oft nicht praktikabel und würde selbst zur Wartungslast. Hier ist es sinnvoller, den generierenden Code klar zu strukturieren und die Testmethode selbst mit einer aussagekräftigen Assertion-Fehlermeldung auszustatten.

Auch bei sehr kurzen Data Providern mit nur zwei selbsterklärenden Einträgen, etwa 'true' und 'false' als einziger Parameter, bringt eine Benennung oft wenig zusätzlichen Wert und kann die Provider-Methode unnötig aufblähen. Named Datasets sind also ein Werkzeug für den Regelfall mittelgroßer, fachlich unterscheidbarer Testfälle, kein dogmatisches Muss für jeden Data Provider ausnahmslos.

9. Fazit: kleine Änderung, großer Effekt auf die Diagnosegeschwindigkeit

Der Umstieg von nummerierten auf benannte Data-Provider-Einträge kostet nahezu keinen zusätzlichen Aufwand, verändert aber spürbar, wie schnell ein Team fehlgeschlagene Tests versteht. Statt eine Nummer im Code nachzuschlagen, steht der fachliche Kontext direkt in der Fehlermeldung, was besonders bei CI-Benachrichtigungen und Slack-Meldungen den entscheidenden Unterschied macht, ob ein Fehler sofort verstanden wird oder erst nach Rückfrage.

Als Faustregel gilt: Jeder neue Data Provider mit mehr als zwei Einträgen sollte von Anfang an benannte Keys verwenden, und bei jeder Berührung eines alten, nummerierten Providers sollte die Benennung gleich mit nachgezogen werden. Die folgende Tabelle stellt beide Varianten noch einmal gegenüber.

10. Zusammenfassung

11. FAQ: Named Datasets: Das Wichtigste auf einen Blick