PHPUnit Attribute statt Annotationen: Migration und Praxis

1. Warum Attribute die Docblock-Annotationen ablösen

Seit PHP 8.0 gehören Attribute zur Sprache selbst, keine Kommentar-Konvention mehr, sondern echte, vom Parser verstandene Metadaten. PHPUnit hat diese Möglichkeit ab Version 10 konsequent aufgegriffen: Fast jede @annotation aus dem Docblock hat inzwischen ein direktes Attribut-Gegenstück, und ab PHPUnit 12 sind die alten Annotationen für die meisten Fälle bereits entfernt. Wer eine Testsuite langfristig pflegt, kommt an dieser Umstellung also nicht vorbei.

Der Unterschied ist mehr als Kosmetik. Ein Docblock-Kommentar wie @dataProvider provideCases ist für PHP selbst unsichtbar, er wird nur von PHPUnits eigenem Reflection-Parser als Text ausgewertet. Ein Tippfehler im Methodennamen fällt frühestens beim Testlauf auf, manchmal auch dann nicht, wenn PHPUnit den Fehler stillschweigend ignoriert. Ein #[DataProvider('provideCases')]-Attribut dagegen wird von der PHP-Engine selbst geparst und ist damit von Werkzeugen wie PHPStan oder der IDE direkt greifbar.

2. Das Grundproblem der alten @annotation-Syntax

Annotationen leben in Kommentaren, und Kommentare sind für den PHP-Compiler bedeutungslose Zeichenketten. Das bringt drei konkrete Nachteile mit sich: Erstens gibt es keine Syntaxprüfung, ein falsch geschriebenes @dataProvidr fällt nicht auf. Zweitens funktioniert automatisiertes Refactoring nicht zuverlässig, benennt man eine Data-Provider-Methode über die IDE um, bleibt der Verweis im Docblock oft unverändert zurück. Drittens sind Docblocks nicht typsicher, es gibt keine Möglichkeit, die Struktur der Annotation zur Entwicklungszeit zu validieren.

In der Praxis führen diese Lücken zu einer bestimmten Klasse von Bugs: Tests, die vermeintlich laufen, aber in Wirklichkeit gar nicht ausgeführt werden, weil eine Annotation einen Tippfehler enthält und PHPUnit die Methode stillschweigend als normale Hilfsmethode statt als Test behandelt. Solche stillen Fehlkonfigurationen sind besonders tückisch, weil die CI-Pipeline grün bleibt, während wichtige Testfälle in Wahrheit nie liefen. Attribute schließen diese Lücke, weil ein falsch geschriebenes Attribut sofort als Syntaxfehler oder als unbekannte Klasse auffällt.

3. #[Test] statt @test: Der einfachste Umstieg

Der naheliegendste Einstieg ist das #[Test]-Attribut, das die Notwendigkeit ersetzt, Testmethoden mit dem Präfix test zu benennen oder sie per @test-Docblock zu markieren. Damit lassen sich Methodennamen wählen, die die Absicht klar beschreiben, ohne redundantes test-Präfix vorneweg. Das folgende Beispiel zeigt beide Varianten nebeneinander, alt und neu, für dieselbe Testklasse.

Wichtig ist: #[Test] ist rein syntaktischer Zucker, PHPUnit erkennt weiterhin auch Methoden, die mit test beginnen, ganz ohne Attribut. Der Vorteil des Attributs liegt also nicht in einer neuen Fähigkeit, sondern in der Freiheit, sprechende Methodennamen zu wählen und gleichzeitig explizit zu machen, dass es sich um einen Test handelt, was besonders bei Hilfsmethoden innerhalb der Testklasse die Lesbarkeit verbessert.

<?php

declare(strict_types=1);

namespace Mironsoft\Tests\Unit;

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

// Alte Docblock-Annotation
final class OrderCalculatorAnnotationTest extends TestCase
{
    /**
     * @test
     */
    public function calculatesTotalWithTax(): void
    {
        self::assertSame(119, (new OrderCalculator())->totalWithTax(100, 19));
    }
}

// Neue Attribute-Syntax
final class OrderCalculatorAttributeTest extends TestCase
{
    #[Test]
    public function berechnetGesamtbetragMitSteuer(): void
    {
        self::assertSame(119, (new OrderCalculator())->totalWithTax(100, 19));
    }
}

4. #[DataProvider] mit typsicherer Methodenreferenz

Data Provider profitieren am stärksten vom Umstieg, weil hier der Bezug zwischen Testmethode und Provider-Methode früher rein textuell war. Mit #[DataProvider('providesTaxCases')] bleibt zwar weiterhin ein String-Argument nötig, PHPUnit selbst prüft aber bei der Testausführung sofort, ob die referenzierte Methode existiert, und moderne IDEs bieten Navigation und Umbenennungs-Unterstützung für diesen Fall inzwischen deutlich zuverlässiger an als für Docblock-Text.

Seit PHPUnit 10 lässt sich außerdem dieselbe Data-Provider-Methode über mehrere Testmethoden hinweg per mehrfachem Attribut wiederverwenden, und mit #[DataProviderExternal] kann sogar auf eine Provider-Methode in einer anderen Klasse verwiesen werden, was gemeinsame Testdaten über mehrere Testklassen hinweg erheblich vereinfacht, ohne Vererbungshierarchien nur für den Datenaustausch aufzubauen.

<?php

declare(strict_types=1);

namespace Mironsoft\Tests\Unit;

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

final class TaxCalculatorTest extends TestCase
{
    #[Test]
    #[DataProvider('providesTaxCases')]
    public function berechnetSteuerKorrekt(int $netPrice, int $taxRate, int $expected): void
    {
        self::assertSame($expected, (new TaxCalculator())->calculate($netPrice, $taxRate));
    }

    public static function providesTaxCases(): array
    {
        return [
            'Standardsatz 19 Prozent' => [100, 19, 19],
            'Ermaessigter Satz 7 Prozent' => [100, 7, 7],
            'Nullsatz bei Export' => [100, 0, 0],
        ];
    }
}

5. #[Group], #[CoversClass] und weitere nützliche Attribute

Über #[Test] und #[DataProvider] hinaus deckt PHPUnit inzwischen fast das gesamte Annotations-Vokabular per Attribut ab: #[Group('checkout')] zum Filtern von Testläufen, #[CoversClass(OrderCalculator::class)] für die Code-Coverage-Zuordnung, #[Depends('testCreatesOrder')] für Testabhängigkeiten und #[RunInSeparateProcess] für isolierte Prozessausführung. Der große Vorteil gegenüber der Docblock-Variante ist, dass #[CoversClass(OrderCalculator::class)] eine echte Klassenreferenz ist, die bei einer Umbenennung der Klasse automatisch mitgeht.

Besonders in größeren Teams zahlt sich das aus: Ein CI-Job, der mit --group checkout nur bestimmte Tests ausführt, ist mit Attributen weniger fehleranfällig, weil Tippfehler im Gruppennamen zwar weiterhin möglich sind, aber die Klassenreferenzen bei #[CoversClass] und #[Depends] durch die PHP-Engine selbst validiert werden, sobald die referenzierte Klasse oder Methode nicht existiert.

<?php

declare(strict_types=1);

namespace Mironsoft\Tests\Unit;

use PHPUnit\Framework\Attributes\CoversClass;
use PHPUnit\Framework\Attributes\Depends;
use PHPUnit\Framework\Attributes\Group;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;

#[CoversClass(OrderRepository::class)]
#[Group('checkout')]
final class OrderRepositoryTest extends TestCase
{
    #[Test]
    public function erstelltNeueBestellung(): int
    {
        $id = (new OrderRepository())->create(['sku' => 'ABC-123']);
        self::assertGreaterThan(0, $id);

        return $id;
    }

    #[Test]
    #[Depends('erstelltNeueBestellung')]
    public function findetErstellteBestellung(int $orderId): void
    {
        $order = (new OrderRepository())->find($orderId);
        self::assertSame('ABC-123', $order->getSku());
    }
}

6. Migrationsstrategie für bestehende Testsuiten

Eine gewachsene Testsuite mit hunderten Docblock-Annotationen von Hand umzustellen, ist unrealistisch und fehleranfällig. Der pragmatische Weg führt über automatisierte Refactoring-Werkzeuge: Rector bringt seit Version 0.15 fertige Regelsets für genau diesen Zweck mit, etwa AnnotationToAttributeRector, das @dataProvider, @test, @group und weitere gängige Annotationen automatisch in die passenden Attribute umwandelt, inklusive korrekter use-Statements.

Der empfohlene Ablauf ist eine schrittweise Migration statt eines großen Rewrites: Zunächst wird Rector auf einem isolierten Testverzeichnis ausgeführt, das Ergebnis manuell durchgesehen, dann in kleinen Pull Requests gemergt. So bleibt jede Änderung nachvollziehbar, und Regressionen lassen sich sofort einer konkreten Umstellung zuordnen, statt in einem riesigen Diff unterzugehen, der kaum noch sinnvoll reviewt werden kann.

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\PHPUnit\Set\PHPUnitSetList;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__ . '/tests',
    ]);

    // Wandelt @test, @dataProvider, @group etc. in Attribute um
    $rectorConfig->sets([
        PHPUnitSetList::PHPUNIT_100,
        PHPUnitSetList::ANNOTATIONS_TO_ATTRIBUTES,
    ]);
};

7. Mischbetrieb während der Umstellung und Deprecation-Warnungen

Während der Migrationsphase können Annotationen und Attribute in derselben Testsuite parallel existieren, PHPUnit erlaubt das ausdrücklich und wertet beide Formen gleichwertig aus. Problematisch wird es erst, wenn beide Formen gleichzeitig auf derselben Methode stehen und widersprüchliche Angaben machen, etwa ein anderer Data-Provider-Name im Docblock als im Attribut, hier gewinnt das Attribut, was zu verwirrenden Testausführungen führen kann, wenn das nicht bekannt ist.

Ab PHPUnit 10 erscheinen bei Nutzung veralteter Annotationen bereits Deprecation-Hinweise in der Testausgabe, ab PHPUnit 12 sind einige Annotationen wie @dataProvider vollständig entfernt. Wer heute noch auf einer älteren PHPUnit-Version arbeitet, sollte die Migration nicht aufschieben, sondern die Deprecation-Warnungen als konkreten, priorisierbaren Arbeitsauftrag behandeln, bevor ein PHPUnit-Upgrade die Testsuite ohne Vorwarnung bricht.

8. IDE-Unterstützung: Refactoring, Find Usages, statische Analyse

Der vielleicht größte Alltagsgewinn zeigt sich in der IDE. PhpStorm erkennt #[DataProvider('provideCases')] als echte Referenz auf eine Methode: Find Usages funktioniert, Rename Refactoring aktualisiert das Attribut automatisch mit, und Navigation per Klick springt direkt zur Provider-Methode. Bei der alten Docblock-Variante war all das bestenfalls textbasierte Heuristik, die bei komplexeren Umbenennungen regelmäßig versagte.

Auch statische Analyse profitiert: PHPStan und Psalm können mit dem PHPUnit-Erweiterungspaket #[CoversClass]-Referenzen validieren und warnen, wenn eine referenzierte Klasse nicht existiert oder umbenannt wurde. In CI-Pipelines lässt sich das mit einer PHPStan-Stufe kombinieren, die genau solche gebrochenen Referenzen als Fehler markiert, lange bevor ein Entwickler den Testlauf überhaupt manuell startet.

<?php

declare(strict_types=1);

namespace Mironsoft\Tests\Unit;

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

// PHPStan (mit phpstan-phpunit) meldet einen Fehler,
// wenn OrderCalculator umbenannt oder geloescht wird,
// weil die Klassenreferenz im Attribut ungueltig wird.
#[CoversClass(OrderCalculator::class)]
final class OrderCalculatorCoverageTest extends TestCase
{
    #[Test]
    public function prueftRundungAufZweiNachkommastellen(): void
    {
        self::assertSame(33.34, (new OrderCalculator())->splitEqually(100.0, 3));
    }
}

9. Praxisfazit: Wann sich die Migration lohnt

Für neue Testsuiten ist die Antwort klar: Attribute von Anfang an nutzen, es gibt keinen Grund mehr, mit der alten Docblock-Syntax zu starten. Für bestehende, gewachsene Testsuiten hängt das Tempo der Migration vom aktuellen PHPUnit-Stand ab: Wer bereits auf PHPUnit 10 oder 11 läuft, sollte die Umstellung planen, aber nicht überstürzen, wer noch auf PHPUnit 9 oder älter sitzt, sollte Attribute erst nach dem PHPUnit-Upgrade einführen.

In der Praxis zeigt sich, dass der Rector-gestützte Umstieg selbst bei mehreren hundert Testmethoden innerhalb weniger Stunden Reviewzeit machbar ist, weil die Transformation mechanisch und gut testbar ist, der Testlauf selbst dient ja als eingebauter Regressionstest für die Migration. Die folgende Tabelle fasst die wichtigsten Annotation-zu-Attribut-Entsprechungen zusammen.

10. Zusammenfassung

11. FAQ: PHPUnit Attribute: Das Wichtigste auf einen Blick