feat: introduce PhpUnitAttributesFixer (#7831)

.php-cs-fixer.php-highest.php

@@ -24,6 +24,7 @@
 $config->setRules(array_merge($config->getRules(), [
     '@PHP83Migration' => true,
     '@PHP80Migration:risky' => true,
+    'php_unit_attributes' => true,
 ]));
 
 return $config;

doc/rules/index.rst

@@ -637,6 +637,9 @@ PHP Tag
 PHPUnit
 -------
 
+- `php_unit_attributes <./php_unit/php_unit_attributes.rst>`_
+
+  PHPUnit attributes must be used over their respective PHPDoc-based annotations.
 - `php_unit_construct <./php_unit/php_unit_construct.rst>`_ *(risky)*
 
   PHPUnit assertion method calls like ``->assertSame(true, $foo)`` should be written with dedicated method like ``->assertTrue($foo)``.

doc/rules/php_unit/php_unit_attributes.rst

@@ -0,0 +1,40 @@
+============================
+Rule ``php_unit_attributes``
+============================
+
+PHPUnit attributes must be used over their respective PHPDoc-based annotations.
+
+Examples
+--------
+
+Example #1
+~~~~~~~~~~
+
+.. code-block:: diff
+
+   --- Original
+   +++ New
+    <?php
+    /**
+   - * @covers \VendorName\Foo
+     * @internal
+     */
+   +#[\PHPUnit\Framework\Attributes\CoversClass(\VendorName\Foo::class)]
+    final class FooTest extends TestCase {
+        /**
+         * @param int $expected
+         * @param int $actual
+   -     * @dataProvider giveMeSomeData
+   -     * @requires PHP 8.0
+         */
+   +    #[\PHPUnit\Framework\Attributes\DataProvider('giveMeSomeData')]
+   +    #[\PHPUnit\Framework\Attributes\RequiresPhp('8.0')]
+        public function testSomething($expected, $actual) {}
+    }
+References
+----------
+
+- Fixer class: `PhpCsFixer\\Fixer\\PhpUnit\\PhpUnitAttributesFixer <./../../../src/Fixer/PhpUnit/PhpUnitAttributesFixer.php>`_
+- Test class: `PhpCsFixer\\Tests\\Fixer\\PhpUnit\\PhpUnitAttributesFixerTest <./../../../tests/Fixer/PhpUnit/PhpUnitAttributesFixerTest.php>`_
+
+The test class defines officially supported behaviour. Each test case is a part of our backward compatibility promise.

src/Fixer/AbstractPhpUnitFixer.php

@@ -28,7 +28,7 @@
  */
 abstract class AbstractPhpUnitFixer extends AbstractFixer
 {
-    final public function isCandidate(Tokens $tokens): bool
+    public function isCandidate(Tokens $tokens): bool
     {
         return $tokens->isAllTokenKindsFound([T_CLASS, T_STRING]);
     }

src/Fixer/Import/FullyQualifiedStrictTypesFixer.php

@@ -180,7 +180,7 @@ public function foo(): \Other\FunctionReturnType
      * {@inheritdoc}
      *
      * Must run before NoSuperfluousPhpdocTagsFixer, OrderedImportsFixer, OrderedInterfacesFixer, StatementIndentationFixer.
-     * Must run after ClassKeywordFixer, PhpdocToReturnTypeFixer.
+     * Must run after ClassKeywordFixer, PhpUnitAttributesFixer, PhpdocToReturnTypeFixer.
      */
     public function getPriority(): int
     {