#[RequiresEnvironmentVariable]

src/Framework/Attributes/RequiresEnvironmentVariable.php

@@ -0,0 +1,40 @@
+<?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;
+
+/**
+ * @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 <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;
+
+/**
+ * @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 <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\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 <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;
+
+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(),