PHPUnit Attributes Instead of Annotations: Migration and Practice

1. Why attributes are replacing docblock annotations

Since PHP 8.0, attributes have been part of the language itself, no longer a comment convention but real metadata understood by the parser. PHPUnit has embraced this capability consistently starting with version 10: almost every @annotation from the docblock now has a direct attribute counterpart, and as of PHPUnit 12 the old annotations have already been removed for most cases. Anyone maintaining a test suite long term cannot avoid this transition.

The difference is more than cosmetic. A docblock comment like @dataProvider provideCases is invisible to PHP itself, it is only evaluated as text by PHPUnit's own reflection parser. A typo in the method name shows up at the earliest during a test run, sometimes not even then, if PHPUnit silently ignores the mistake. A #[DataProvider('provideCases')] attribute, on the other hand, is parsed by the PHP engine itself and is therefore directly accessible to tools like PHPStan or the IDE.

2. The core problem with the old @annotation syntax

Annotations live inside comments, and comments are meaningless strings to the PHP compiler. That brings three concrete downsides: first, there is no syntax check, a misspelled @dataProvidr goes unnoticed. Second, automated refactoring does not work reliably, renaming a data provider method through the IDE often leaves the reference in the docblock untouched. Third, docblocks are not type safe, there is no way to validate the structure of the annotation at development time.

In practice these gaps lead to a particular class of bugs: tests that appear to run but are in fact never executed, because an annotation contains a typo and PHPUnit silently treats the method as a regular helper instead of a test. Such silent misconfigurations are especially treacherous because the CI pipeline stays green while important test cases never actually ran. Attributes close this gap, because a misspelled attribute immediately shows up as a syntax error or an unknown class.

3. #[Test] instead of @test: the simplest starting point

The most obvious entry point is the #[Test] attribute, which removes the need to prefix test methods with test or mark them via an @test docblock. This allows choosing method names that clearly describe the intent, without a redundant test prefix up front. The example below shows both variants side by side, old and new, for the same test class.

It is worth noting: #[Test] is purely syntactic sugar, PHPUnit still recognizes methods that start with test, with no attribute at all. The benefit of the attribute is therefore not a new capability, but the freedom to choose expressive method names while explicitly marking them as tests, which is especially helpful for readability with helper methods inside the test class.

<?php

declare(strict_types=1);

namespace Mironsoft\Tests\Unit;

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

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

// New attribute syntax
final class OrderCalculatorAttributeTest extends TestCase
{
    #[Test]
    public function itCalculatesTotalWithTax(): void
    {
        self::assertSame(119, (new OrderCalculator())->totalWithTax(100, 19));
    }
}

4. #[DataProvider] with a type safe method reference

Data providers benefit the most from the switch, because previously the link between a test method and its provider method was purely textual. With #[DataProvider('providesTaxCases')] a string argument is still required, but PHPUnit itself checks immediately during a test run whether the referenced method exists, and modern IDEs now offer navigation and rename support for this case far more reliably than for docblock text.

Since PHPUnit 10, the same data provider method can also be reused across multiple test methods by repeating the attribute, and #[DataProviderExternal] can even reference a provider method in a different class, which considerably simplifies sharing test data across multiple test classes without building inheritance hierarchies purely for data exchange.

<?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 itCalculatesTaxCorrectly(int $netPrice, int $taxRate, int $expected): void
    {
        self::assertSame($expected, (new TaxCalculator())->calculate($netPrice, $taxRate));
    }

    public static function providesTaxCases(): array
    {
        return [
            'standard rate 19 percent' => [100, 19, 19],
            'reduced rate 7 percent' => [100, 7, 7],
            'zero rate on export' => [100, 0, 0],
        ];
    }
}

5. #[Group], #[CoversClass] and other useful attributes

Beyond #[Test] and #[DataProvider], PHPUnit now covers almost the entire annotation vocabulary via attributes: #[Group('checkout')] for filtering test runs, #[CoversClass(OrderCalculator::class)] for code coverage mapping, #[Depends('testCreatesOrder')] for test dependencies, and #[RunInSeparateProcess] for isolated process execution. The big advantage over the docblock variant is that #[CoversClass(OrderCalculator::class)] is a real class reference that automatically follows a class rename.

This pays off especially in larger teams: a CI job that runs only certain tests with --group checkout is less error prone with attributes, because typos in the group name are still possible, but the class references inside #[CoversClass] and #[Depends] are validated by the PHP engine itself as soon as the referenced class or method does not exist.

<?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 itCreatesNewOrder(): int
    {
        $id = (new OrderRepository())->create(['sku' => 'ABC-123']);
        self::assertGreaterThan(0, $id);

        return $id;
    }

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

6. A migration strategy for existing test suites

Converting a grown test suite with hundreds of docblock annotations by hand is unrealistic and error prone. The pragmatic path runs through automated refactoring tools: Rector has shipped ready made rule sets for exactly this purpose since version 0.15, including AnnotationToAttributeRector, which automatically converts @dataProvider, @test, @group, and other common annotations into the matching attributes, including the correct use statements.

The recommended flow is a step by step migration rather than one large rewrite: first run Rector on an isolated test directory, manually review the result, then merge in small pull requests. This keeps every change traceable, and regressions can immediately be attributed to a specific conversion, instead of getting lost in one giant diff that can barely be reviewed meaningfully anymore.

<?php

declare(strict_types=1);

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

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

    // Converts @test, @dataProvider, @group etc. into attributes
    $rectorConfig->sets([
        PHPUnitSetList::PHPUNIT_100,
        PHPUnitSetList::ANNOTATIONS_TO_ATTRIBUTES,
    ]);
};

7. Mixed operation during the switch and deprecation warnings

During the migration phase, annotations and attributes can coexist in the same test suite, PHPUnit explicitly allows this and evaluates both forms equally. Problems only arise when both forms appear on the same method with conflicting values, for example a different data provider name in the docblock than in the attribute, here the attribute wins, which can lead to confusing test execution if this behavior is not known.

Starting with PHPUnit 10, using deprecated annotations already produces deprecation notices in the test output, and as of PHPUnit 12 some annotations such as @dataProvider have been fully removed. Anyone still working on an older PHPUnit version should not postpone the migration, but treat the deprecation warnings as a concrete, prioritizable task before a PHPUnit upgrade breaks the test suite without warning.

8. IDE support: refactoring, find usages, static analysis

Perhaps the biggest everyday win shows up in the IDE. PhpStorm recognizes #[DataProvider('provideCases')] as a real reference to a method: Find Usages works, Rename refactoring automatically updates the attribute too, and click through navigation jumps directly to the provider method. With the old docblock variant, all of this was at best text based heuristics that regularly failed with more complex renames.

Static analysis benefits too: PHPStan and Psalm, with the PHPUnit extension package, can validate #[CoversClass] references and warn when a referenced class no longer exists or has been renamed. In CI pipelines this can be combined with a PHPStan stage that flags exactly such broken references as errors, long before a developer even manually starts the test run.

<?php

declare(strict_types=1);

namespace Mironsoft\Tests\Unit;

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

// PHPStan (with phpstan-phpunit) reports an error if
// OrderCalculator is renamed or deleted, because the
// class reference inside the attribute becomes invalid.
#[CoversClass(OrderCalculator::class)]
final class OrderCalculatorCoverageTest extends TestCase
{
    #[Test]
    public function itRoundsToTwoDecimalPlaces(): void
    {
        self::assertSame(33.34, (new OrderCalculator())->splitEqually(100.0, 3));
    }
}

9. Practical takeaway: when the migration is worth it

For new test suites the answer is clear: use attributes from the start, there is no longer any reason to begin with the old docblock syntax. For existing, grown test suites, the pace of migration depends on the current PHPUnit version: teams already running PHPUnit 10 or 11 should plan the switch but need not rush it, teams still on PHPUnit 9 or older should introduce attributes only after the PHPUnit upgrade.

In practice, a Rector supported switch is achievable within a few hours of review time even with several hundred test methods, because the transformation is mechanical and well testable, the test run itself serves as a built in regression test for the migration. The table below summarizes the most important annotation to attribute equivalents.

10. Summary

11. FAQ: PHPUnit Attributes: The Essentials at a Glance