#[RequiresPhpunitExtension] attribute

nikophil · nikophil · commit aa69cc003c7f · 2024-08-19T17:27:25.000+02:00
diff --git a/src/Framework/Attributes/RequiresPhpunitExtension.php b/src/Framework/Attributes/RequiresPhpunitExtension.php
@@ -0,0 +1,43 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Framework\Attributes;
+
+use Attribute;
+use PHPUnit\Runner\Extension\Extension;
+
+/**
+ * @immutable
+ *
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
+final readonly class RequiresPhpunitExtension
+{
+    /**
+     * @var list<class-string<Extension>>
+     */
+    private array $extensionClasses;
+
+    /**
+     * @param class-string<Extension> $extensionClasses
+     */
+    public function __construct(string ...$extensionClasses)
+    {
+        $this->extensionClasses = $extensionClasses;
+    }
+
+    /**
+     * @return list<class-string<Extension>>
+     */
+    public function extensionClasses(): array
+    {
+        return $this->extensionClasses;
+    }
+}
diff --git a/src/Metadata/Api/Requirements.php b/src/Metadata/Api/Requirements.php
@@ -13,9 +13,12 @@
 use const PHP_OS_FAMILY;
 use const PHP_VERSION;
 use function addcslashes;
+use function array_column;
+use function array_diff;
 use function assert;
 use function extension_loaded;
 use function function_exists;
+use function implode;
 use function ini_get;
 use function method_exists;
 use function phpversion;
@@ -29,8 +32,10 @@
 use PHPUnit\Metadata\RequiresPhp;
 use PHPUnit\Metadata\RequiresPhpExtension;
 use PHPUnit\Metadata\RequiresPhpunit;
+use PHPUnit\Metadata\RequiresPhpunitExtension;
 use PHPUnit\Metadata\RequiresSetting;
 use PHPUnit\Runner\Version;
+use PHPUnit\TextUI\Configuration\Registry as ConfigurationRegistry;
 
 /**
  * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
@@ -86,6 +91,21 @@ public function requirementsNotSatisfiedFor(string $className, string $methodNam
                 }
             }
 
+            if ($metadata->isRequiresPhpunitExtension()) {
+                assert($metadata instanceof RequiresPhpunitExtension);
+
+                $configuration = ConfigurationRegistry::get();
+
+                $extensionBootstrappers = array_column($configuration->extensionBootstrappers(), 'className');
+
+                if ($configuration->noExtensions() || $missingExtensions = array_diff($metadata->extensionClasses(), $extensionBootstrappers)) {
+                    $notSatisfied[] = sprintf(
+                        'PHPUnit extension(s) "%s" required.',
+                        implode('", "', $missingExtensions ?? $metadata->extensionClasses()),
+                    );
+                }
+            }
+
             if ($metadata->isRequiresOperatingSystemFamily()) {
                 assert($metadata instanceof RequiresOperatingSystemFamily);
 
diff --git a/src/Metadata/Metadata.php b/src/Metadata/Metadata.php
@@ -10,6 +10,7 @@
 namespace PHPUnit\Metadata;
 
 use PHPUnit\Metadata\Version\Requirement;
+use PHPUnit\Runner\Extension\Extension;
 
 /**
  * @immutable
@@ -390,6 +391,22 @@ public static function requiresPhpunitOnMethod(Requirement $versionRequirement):
         return new RequiresPhpunit(self::METHOD_LEVEL, $versionRequirement);
     }
 
+    /**
+     * @param class-string<Extension> $extensionClasses
+     */
+    public static function requiresPhpunitExtensionOnClass(string ...$extensionClasses): RequiresPhpunitExtension
+    {
+        return new RequiresPhpunitExtension(self::CLASS_LEVEL, ...$extensionClasses);
+    }
+
+    /**
+     * @param class-string<Extension> $extensionClasses
+     */
+    public static function requiresPhpunitExtensionOnMethod(string ...$extensionClasses): RequiresPhpunitExtension
+    {
+        return new RequiresPhpunitExtension(self::METHOD_LEVEL, ...$extensionClasses);
+    }
+
     /**
      * @param non-empty-string $setting
      * @param non-empty-string $value
@@ -831,6 +848,14 @@ public function isRequiresPhpunit(): bool
         return false;
     }
 
+    /**
+     * @phpstan-assert-if-true RequiresPhpunitExtension $this
+     */
+    public function isRequiresPhpunitExtension(): bool
+    {
+        return false;
+    }
+
     /**
      * @phpstan-assert-if-true RequiresSetting $this
      */
diff --git a/src/Metadata/MetadataCollection.php b/src/Metadata/MetadataCollection.php
@@ -483,6 +483,16 @@ public function isRequiresPhpunit(): self
         );
     }
 
+    public function isRequiresPhpunitExtension(): self
+    {
+        return new self(
+            ...array_filter(
+                $this->metadata,
+                static fn (Metadata $metadata): bool => $metadata->isRequiresPhpunitExtension(),
+            ),
+        );
+    }
+
     public function isRequiresSetting(): self
     {
         return new self(
diff --git a/src/Metadata/Parser/AttributeParser.php b/src/Metadata/Parser/AttributeParser.php
@@ -58,6 +58,7 @@
 use PHPUnit\Framework\Attributes\RequiresPhp;
 use PHPUnit\Framework\Attributes\RequiresPhpExtension;
 use PHPUnit\Framework\Attributes\RequiresPhpunit;
+use PHPUnit\Framework\Attributes\RequiresPhpunitExtension;
 use PHPUnit\Framework\Attributes\RequiresSetting;
 use PHPUnit\Framework\Attributes\RunClassInSeparateProcess;
 use PHPUnit\Framework\Attributes\RunInSeparateProcess;
@@ -288,6 +289,15 @@ public function forClass(string $className): MetadataCollection
 
                     break;
 
+                case RequiresPhpunitExtension::class:
+                    assert($attributeInstance instanceof RequiresPhpunitExtension);
+
+                    $result[] = Metadata::requiresPhpunitExtensionOnClass(
+                        ...$attributeInstance->extensionClasses(),
+                    );
+
+                    break;
+
                 case RequiresSetting::class:
                     assert($attributeInstance instanceof RequiresSetting);
 
@@ -641,6 +651,15 @@ public function forMethod(string $className, string $methodName): MetadataCollec
 
                     break;
 
+                case RequiresPhpunitExtension::class:
+                    assert($attributeInstance instanceof RequiresPhpunitExtension);
+
+                    $result[] = Metadata::requiresPhpunitExtensionOnMethod(
+                        ...$attributeInstance->extensionClasses(),
+                    );
+
+                    break;
+
                 case RequiresSetting::class:
                     assert($attributeInstance instanceof RequiresSetting);
 
diff --git a/src/Metadata/RequiresPhpunitExtension.php b/src/Metadata/RequiresPhpunitExtension.php
@@ -0,0 +1,48 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Metadata;
+
+use PHPUnit\Runner\Extension\Extension;
+
+/**
+ * @immutable
+ *
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+final readonly class RequiresPhpunitExtension extends Metadata
+{
+    /**
+     * @var list<class-string<Extension>>
+     */
+    private array $extensionClasses;
+
+    /**
+     * @param class-string<Extension> $extensionClasses
+     */
+    public function __construct(int $level, string ...$extensionClasses)
+    {
+        parent::__construct($level);
+
+        $this->extensionClasses = $extensionClasses;
+    }
+
+    public function isRequiresPhpunitExtension(): true
+    {
+        return true;
+    }
+
+    /**
+     * @return list<class-string<Extension>>
+     */
+    public function extensionClasses(): array
+    {
+        return $this->extensionClasses;
+    }
+}
diff --git a/tests/_files/Metadata/Attribute/tests/RequiresPhpunitExtensionTest.php b/tests/_files/Metadata/Attribute/tests/RequiresPhpunitExtensionTest.php
@@ -0,0 +1,22 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\TestFixture\Metadata\Attribute;
+
+use PHPUnit\Framework\Attributes\RequiresPhpunitExtension;
+use PHPUnit\Framework\TestCase;
+
+#[RequiresPhpunitExtension(SomeClass::class)]
+final class RequiresPhpunitExtensionTest extends TestCase
+{
+    #[RequiresPhpunitExtension(SomeClass::class, SomeOtherClass::class)]
+    public function testOne(): void
+    {
+    }
+}
diff --git a/tests/_files/RequirementsTest.php b/tests/_files/RequirementsTest.php
@@ -16,6 +16,7 @@
 use PHPUnit\Framework\Attributes\RequiresPhp;
 use PHPUnit\Framework\Attributes\RequiresPhpExtension;
 use PHPUnit\Framework\Attributes\RequiresPhpunit;
+use PHPUnit\Framework\Attributes\RequiresPhpunitExtension;
 use PHPUnit\Framework\Attributes\RequiresSetting;
 use PHPUnit\Framework\Attributes\TestDox;
 use PHPUnit\Framework\Attributes\Ticket;
@@ -363,4 +364,9 @@ public function testVersionConstraintRegexpIgnoresWhitespace(): void
     public function testSettingDisplayErrorsOn(): void
     {
     }
+
+    #[RequiresPhpunitExtension(SomeClass::class, SomeOtherClass::class)]
+    public function testPHPUnitExtensionRequired(): void
+    {
+    }
 }
diff --git a/tests/unit/Metadata/Api/RequirementsTest.php b/tests/unit/Metadata/Api/RequirementsTest.php
@@ -123,6 +123,9 @@ public static function missingRequirementsProvider(): array
                 'PHP ^1.0 is required.',
                 'PHPUnit ^2.0 is required.',
             ]],
+            ['testPHPUnitExtensionRequired', [
+                'PHPUnit extension(s) "PHPUnit\TestFixture\SomeClass", "PHPUnit\TestFixture\SomeOtherClass" required.',
+            ]],
         ];
     }
 
diff --git a/tests/unit/Metadata/MetadataCollectionTest.php b/tests/unit/Metadata/MetadataCollectionTest.php
@@ -16,6 +16,7 @@
 use PHPUnit\Framework\TestCase;
 use PHPUnit\Metadata\Version\ComparisonRequirement;
 use PHPUnit\Util\VersionComparisonOperator;
+use stdClass;
 
 #[CoversClass(MetadataCollection::class)]
 #[CoversClass(MetadataCollectionIterator::class)]
@@ -48,6 +49,7 @@
 #[UsesClass(RequiresPhp::class)]
 #[UsesClass(RequiresPhpExtension::class)]
 #[UsesClass(RequiresPhpunit::class)]
+#[UsesClass(RequiresPhpunitExtension::class)]
 #[UsesClass(RequiresSetting::class)]
 #[UsesClass(RunClassInSeparateProcess::class)]
 #[UsesClass(RunInSeparateProcess::class)]
@@ -404,6 +406,14 @@ public function test_Can_be_filtered_for_RequiresPhpunit(): void
         $this->assertTrue($collection->asArray()[0]->isRequiresPhpunit());
     }
 
+    public function test_Can_be_filtered_for_RequiresPhpunitExtension(): void
+    {
+        $collection = $this->collectionWithOneOfEach()->isRequiresPhpunitExtension();
+
+        $this->assertCount(1, $collection);
+        $this->assertTrue($collection->asArray()[0]->isRequiresPhpunitExtension());
+    }
+
     public function test_Can_be_filtered_for_RequiresSetting(): void
     {
         $collection = $this->collectionWithOneOfEach()->isRequiresSetting();
@@ -563,6 +573,7 @@ private function collectionWithOneOfEach(): MetadataCollection
                         new VersionComparisonOperator('>='),
                     ),
                 ),
+                Metadata::requiresPhpunitExtensionOnClass(stdClass::class),
                 Metadata::requiresSettingOnClass('foo', 'bar'),
                 Metadata::runClassInSeparateProcess(),
                 Metadata::runInSeparateProcess(),
diff --git a/tests/unit/Metadata/MetadataTest.php b/tests/unit/Metadata/MetadataTest.php
diff --git a/tests/unit/Metadata/Parser/AttributeParserTestCase.php b/tests/unit/Metadata/Parser/AttributeParserTestCase.php

Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,7 @@`
`16`	`16`	`use PHPUnit\Framework\Attributes\RequiresPhp;`
`17`	`17`	`use PHPUnit\Framework\Attributes\RequiresPhpExtension;`
`18`	`18`	`use PHPUnit\Framework\Attributes\RequiresPhpunit;`
	`19`	`+use PHPUnit\Framework\Attributes\RequiresPhpunitExtension;`
`19`	`20`	`use PHPUnit\Framework\Attributes\RequiresSetting;`
`20`	`21`	`use PHPUnit\Framework\Attributes\TestDox;`
`21`	`22`	`use PHPUnit\Framework\Attributes\Ticket;`
`@@ -363,4 +364,9 @@ public function testVersionConstraintRegexpIgnoresWhitespace(): void`
`363`	`364`	`public function testSettingDisplayErrorsOn(): void`
`364`	`365`	`{`
`365`	`366`	`}`
	`367`	`+`
	`368`	`+ #[RequiresPhpunitExtension(SomeClass::class, SomeOtherClass::class)]`
	`369`	`+ public function testPHPUnitExtensionRequired(): void`
	`370`	`+ {`
	`371`	`+ }`
`366`	`372`	`}`
Original file line number	Diff line number	Diff line change
`@@ -123,6 +123,9 @@ public static function missingRequirementsProvider(): array`
`123`	`123`	`'PHP ^1.0 is required.',`
`124`	`124`	`'PHPUnit ^2.0 is required.',`
`125`	`125`	`]],`
	`126`	`+ ['testPHPUnitExtensionRequired', [`
	`127`	`+ 'PHPUnit extension(s) "PHPUnit\TestFixture\SomeClass", "PHPUnit\TestFixture\SomeOtherClass" required.',`
	`128`	`+ ]],`
`126`	`129`	`];`
`127`	`130`	`}`
`128`	`131`