#[RequiresEnvironmentVariable]

src/Framework/Attributes/RequiresEnvironmentVariable.php

@@ -0,0 +1,40 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <[email protected]>
+ *
+ * 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;
+
+/**
+ * @immutable
+ *
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+final readonly class RequiresEnvironmentVariable
+{
+    private string $environmentVariableName;
+    private null|bool|int|string $value;
+
+    public function __construct(string $environmentVariableName, null|bool|int|string $value = null)
+    {
+        $this->environmentVariableName = $environmentVariableName;
+        $this->value                   = $value;
+    }
+
+    public function environmentVariableName(): string
+    {
+        return $this->environmentVariableName;
+    }
+
+    public function value(): null|bool|int|string
+    {
+        return $this->value;
+    }
+}

src/Metadata/Api/Requirements.php

@@ -14,6 +14,7 @@
 use const PHP_VERSION;
 use function addcslashes;
 use function array_column;
+use function array_key_exists;
 use function assert;
 use function extension_loaded;
 use function function_exists;
@@ -24,6 +25,7 @@
 use function preg_match;
 use function sprintf;
 use PHPUnit\Metadata\Parser\Registry;
+use PHPUnit\Metadata\RequiresEnvironmentVariable;
 use PHPUnit\Metadata\RequiresFunction;
 use PHPUnit\Metadata\RequiresMethod;
 use PHPUnit\Metadata\RequiresOperatingSystem;
@@ -105,6 +107,24 @@ public function requirementsNotSatisfiedFor(string $className, string $methodNam
                 }
             }
 
+            if ($metadata->isRequiresEnvironmentVariable()) {
+                assert($metadata instanceof RequiresEnvironmentVariable);
+
+                if (!array_key_exists($metadata->environmentVariableName(), $_ENV)) {
+                    $notSatisfied[] = sprintf('Environment variable "%s" is required.', $metadata->environmentVariableName());
+
+                    continue;
+                }
+
+                if ($metadata->value() !== null && $_ENV[$metadata->environmentVariableName()] !== $metadata->value()) {
+                    $notSatisfied[] = sprintf(
+                        'Environment variable "%s" is required to be "%s".',
+                        $metadata->environmentVariableName(),
+                        $metadata->value(),
+                    );
+                }
+            }
+
             if ($metadata->isRequiresOperatingSystemFamily()) {
                 assert($metadata instanceof RequiresOperatingSystemFamily);
 

src/Metadata/Metadata.php

@@ -391,6 +391,16 @@ public static function requiresPhpunitExtensionOnMethod(string $extensionClass):
         return new RequiresPhpunitExtension(self::METHOD_LEVEL, $extensionClass);
     }
 
+    public static function requiresEnvironmentVariableOnClass(string $environmentVariableName, null|int|string $value): RequiresEnvironmentVariable
+    {
+        return new RequiresEnvironmentVariable(self::CLASS_LEVEL, $environmentVariableName, $value);
+    }
+
+    public static function requiresEnvironmentVariableOnMethod(string $environmentVariableName, null|int|string $value): RequiresEnvironmentVariable
+    {
+        return new RequiresEnvironmentVariable(self::METHOD_LEVEL, $environmentVariableName, $value);
+    }
+
     /**
      * @param non-empty-string $setting
      * @param non-empty-string $value
@@ -816,6 +826,14 @@ public function isRequiresPhpunitExtension(): bool
         return false;
     }
 
+    /**
+     * @phpstan-assert-if-true RequiresEnvironmentVariable $this
+     */
+    public function isRequiresEnvironmentVariable(): bool
+    {
+        return false;
+    }
+
     /**
      * @phpstan-assert-if-true RequiresSetting $this
      */

src/Metadata/MetadataCollection.php

@@ -483,6 +483,16 @@ public function isRequiresPhpunitExtension(): self
         );
     }
 
+    public function isRequiresEnvironmentVariable(): self
+    {
+        return new self(
+            ...array_filter(
+                $this->metadata,
+                static fn (Metadata $metadata): bool => $metadata->isRequiresEnvironmentVariable(),
+            ),
+        );
+    }
+
     public function isRequiresSetting(): self
     {
         return new self(

src/Metadata/Parser/AttributeParser.php

@@ -54,6 +54,7 @@
 use PHPUnit\Framework\Attributes\PostCondition;
 use PHPUnit\Framework\Attributes\PreCondition;
 use PHPUnit\Framework\Attributes\PreserveGlobalState;
+use PHPUnit\Framework\Attributes\RequiresEnvironmentVariable;
 use PHPUnit\Framework\Attributes\RequiresFunction;
 use PHPUnit\Framework\Attributes\RequiresMethod;
 use PHPUnit\Framework\Attributes\RequiresOperatingSystem;
@@ -315,6 +316,16 @@ public function forClass(string $className): MetadataCollection
 
                     break;
 
+                case RequiresEnvironmentVariable::class:
+                    assert($attributeInstance instanceof RequiresEnvironmentVariable);
+
+                    $result[] = Metadata::requiresEnvironmentVariableOnClass(
+                        $attributeInstance->environmentVariableName(),
+                        $attributeInstance->value(),
+                    );
+
+                    break;
+
                 case RequiresSetting::class:
                     assert($attributeInstance instanceof RequiresSetting);
 
@@ -691,6 +702,16 @@ public function forMethod(string $className, string $methodName): MetadataCollec
 
                     break;
 
+                case RequiresEnvironmentVariable::class:
+                    assert($attributeInstance instanceof RequiresEnvironmentVariable);
+
+                    $result[] = Metadata::requiresEnvironmentVariableOnMethod(
+                        $attributeInstance->environmentVariableName(),
+                        $attributeInstance->value(),
+                    );
+
+                    break;
+
                 case RequiresSetting::class:
                     assert($attributeInstance instanceof RequiresSetting);
 

src/Metadata/RequiresEnvironmentVariable.php

@@ -0,0 +1,44 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Metadata;
+
+/**
+ * @immutable
+ *
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+final readonly class RequiresEnvironmentVariable extends Metadata
+{
+    private string $environmentVariableName;
+    private null|bool|int|string $value;
+
+    public function __construct(int $level, string $environmentVariableName, null|bool|int|string $value)
+    {
+        parent::__construct($level);
+
+        $this->environmentVariableName = $environmentVariableName;
+        $this->value                   = $value;
+    }
+
+    public function isRequiresEnvironmentVariable(): true
+    {
+        return true;
+    }
+
+    public function environmentVariableName(): string
+    {
+        return $this->environmentVariableName;
+    }
+
+    public function value(): null|bool|int|string
+    {
+        return $this->value;
+    }
+}

tests/_files/Metadata/Attribute/tests/RequiresEnvironmentVariableTest.php

@@ -0,0 +1,23 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <[email protected]>
+ *
+ * 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\RequiresEnvironmentVariable;
+use PHPUnit\Framework\TestCase;
+
+#[RequiresEnvironmentVariable('foo', 'bar')]
+final class RequiresEnvironmentVariableTest extends TestCase
+{
+    #[RequiresEnvironmentVariable('foo')]
+    #[RequiresEnvironmentVariable('bar', 'baz')]
+    public function testOne(): void
+    {
+    }
+}

tests/_files/RequirementsEnvironmentVariableTest.php

@@ -0,0 +1,23 @@
+<?php
+declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\TestFixture;
+
+use PHPUnit\Framework\Attributes\RequiresEnvironmentVariable;
+use PHPUnit\Framework\TestCase;
+
+final class RequirementsEnvironmentVariableTest extends TestCase
+{
+    #[RequiresEnvironmentVariable('foo', 'bar')]
+    #[RequiresEnvironmentVariable('baz')]
+    public function testRequiresEnvironmentVariable(): void
+    {
+    }
+}

tests/unit/Metadata/Api/RequirementsTest.php

@@ -14,6 +14,7 @@
 use PHPUnit\Framework\Attributes\Group;
 use PHPUnit\Framework\Attributes\Small;
 use PHPUnit\Framework\TestCase;
+use PHPUnit\TestFixture\RequirementsEnvironmentVariableTest;
 
 #[CoversClass(Requirements::class)]
 #[Small]
@@ -130,6 +131,12 @@ public static function missingRequirementsProvider(): array
         ];
     }
 
+    protected function tearDown(): void
+    {
+        parent::tearDown();
+        unset($_ENV['foo']);
+    }
+
     #[DataProvider('missingRequirementsProvider')]
     public function testGetMissingRequirements(string $test, array $result): void
     {
@@ -138,4 +145,17 @@ public function testGetMissingRequirements(string $test, array $result): void
             (new Requirements)->requirementsNotSatisfiedFor(\PHPUnit\TestFixture\RequirementsTest::class, $test),
         );
     }
+
+    public function testGetMissingEnvironmentVariableRequirements(): void
+    {
+        $_ENV['foo'] = '';
+
+        $this->assertEquals(
+            [
+                'Environment variable "foo" is required to be "bar".',
+                'Environment variable "baz" is required.',
+            ],
+            (new Requirements)->requirementsNotSatisfiedFor(RequirementsEnvironmentVariableTest::class, 'testRequiresEnvironmentVariable'),
+        );
+    }
 }

tests/unit/Metadata/MetadataCollectionTest.php

@@ -48,6 +48,7 @@
 #[UsesClass(RequiresPhpExtension::class)]
 #[UsesClass(RequiresPhpunit::class)]
 #[UsesClass(RequiresPhpunitExtension::class)]
+#[UsesClass(RequiresEnvironmentVariable::class)]
 #[UsesClass(RequiresSetting::class)]
 #[UsesClass(RunClassInSeparateProcess::class)]
 #[UsesClass(RunInSeparateProcess::class)]
@@ -402,6 +403,14 @@ public function test_Can_be_filtered_for_RequiresPhpunitExtension(): void
         $this->assertTrue($collection->asArray()[0]->isRequiresPhpunitExtension());
     }
 
+    public function test_Can_be_filtered_for_RequiresEnvironmentVariable(): void
+    {
+        $collection = $this->collectionWithOneOfEach()->isRequiresEnvironmentVariable();
+
+        $this->assertCount(1, $collection);
+        $this->assertTrue($collection->asArray()[0]->isRequiresEnvironmentVariable());
+    }
+
     public function test_Can_be_filtered_for_RequiresSetting(): void
     {
         $collection = $this->collectionWithOneOfEach()->isRequiresSetting();
@@ -553,6 +562,7 @@ private function collectionWithOneOfEach(): MetadataCollection
                     ),
                 ),
                 Metadata::requiresPhpunitExtensionOnClass(stdClass::class),
+                Metadata::requiresEnvironmentVariableOnClass('foo', 'bar'),
                 Metadata::requiresSettingOnClass('foo', 'bar'),
                 Metadata::runClassInSeparateProcess(),
                 Metadata::runInSeparateProcess(),