Attributes and conditions API
This reference lists the attributes and conditions that control test discovery and execution.
These signatures are the public API.
After
Namespace: Greenlight\Attribute
Runs at the end of an attempt that has a test instance. It also runs when setup or the test method does not complete.
#[\Attribute(\Attribute::TARGET_METHOD)]
final readonly class AfterThis type does not declare public members.
AllowParallel
Namespace: Greenlight\Attribute
Allows Greenlight to assign tests from one class to different workers.
Do not use this attribute with per-class harness services or #[Isolated].
#[\Attribute(\Attribute::TARGET_CLASS)]
final readonly class AllowParallelThis type does not declare public members.
Before
Namespace: Greenlight\Attribute
Runs the method before each test attempt in the class.
#[\Attribute(\Attribute::TARGET_METHOD)]
final readonly class BeforeThis type does not declare public members.
CoverageIgnore
Namespace: Greenlight\Attribute
Excludes the selected lines from coverage totals, coverage exports, and baseline diffs.
#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_FUNCTION)]
final readonly class CoverageIgnoreThis type does not declare public members.
DataRow
Namespace: Greenlight\Attribute
Supplies one argument list in an attribute for a test method.
The optional label becomes the data-set key in the test ID. A row without a
label uses its position. Use #[DataSet] if an attribute cannot express a
value.
#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
final readonly class DataRow$label
public ?string $label;PHPDoc:
@var non-empty-string|null
$arguments
public array $arguments__construct()
public function __construct(
public array $arguments,
?string $label = null,
)PHPDoc:
@param array<mixed> $arguments@param non-empty-string|null $label@throws \InvalidArgumentException
DataSet
Namespace: Greenlight\Attribute
References a pure public static data provider. Greenlight evaluates the provider during discovery and again in the worker for each class assignment. Return the same data for the same inputs. Do not change external state.
#[\Attribute(\Attribute::TARGET_METHOD)]
final readonly class DataSet$provider
public string $provider;PHPDoc:
@var non-empty-string
$providerClass
public ?string $providerClass;PHPDoc:
@var class-string|null
__construct()
With one argument, $provider names a method on the test class. With two
arguments, it names the provider class and $method names the provider
method.
public function __construct(string $provider, ?string $method = null)PHPDoc:
@param ($method is null ? non-empty-string : class-string) $provider@param non-empty-string|null $method@throws \InvalidArgumentException
Group
Namespace: Greenlight\Attribute
Adds a group name to a test method or all tests in a class. Class and method groups combine. Repeat the attribute to add more groups.
#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
final readonly class Group$name
public string $name;PHPDoc:
@var non-empty-string
__construct()
public function __construct(string $name)PHPDoc:
@param non-empty-string $name@throws \InvalidArgumentException
Isolated
Namespace: Greenlight\Attribute
Assigns a fresh worker process to each selected test during process-pool execution. In-process execution does not provide process isolation.
#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS)]
final readonly class IsolatedThis type does not declare public members.
NoExpectations
Namespace: Greenlight\Attribute
Exempts a test that intentionally verifies no expectations from risky-test detection.
#[\Attribute(\Attribute::TARGET_METHOD)]
final readonly class NoExpectationsThis type does not declare public members.
RequiresResource
Namespace: Greenlight\Attribute
Declares a resource that the assignment for the test requires.
#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
final readonly class RequiresResource$name
public string $name;PHPDoc:
@var non-empty-string
__construct()
public function __construct(string $name)PHPDoc:
@throws \InvalidArgumentException
Retry
Namespace: Greenlight\Attribute
Starts up to $times additional attempts after an unsuccessful test attempt.
If $onlyOn specifies a throwable type, Greenlight starts another attempt
only when the cause has that type.
#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS)]
final readonly class Retry$times
public int $times;PHPDoc:
@var positive-int
$onlyOn
public ?string $onlyOn;PHPDoc:
@var class-string<\Throwable>|null
__construct()
public function __construct(
int $times,
?string $onlyOn = null,
)PHPDoc:
@param class-string<\Throwable>|null $onlyOn@throws \InvalidArgumentException
Skip
Namespace: Greenlight\Attribute
Skips a test method or all tests in a class with the specified reason.
#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS)]
final readonly class Skip$reason
public string $reason;PHPDoc:
@var non-empty-string
__construct()
public function __construct(string $reason)PHPDoc:
@param non-empty-string $reason@throws \InvalidArgumentException If $reason is empty.
SkipUnless
Namespace: Greenlight\Attribute
Skips a test unless the condition returns true.
A worker evaluates the condition. Use only scalar values or null for constructor arguments. Use finite float values.
#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS)]
final readonly class SkipUnless$condition
public string $condition;PHPDoc:
@var class-string<Condition>
$arguments
public array $arguments;PHPDoc:
@var list<mixed>
__construct()
public function __construct(
string $condition,
mixed ...$arguments,
)PHPDoc:
@param class-string<Condition> $condition@throws \InvalidArgumentException
Test
Namespace: Greenlight\Attribute
Identifies a test method. Greenlight captures test output by default.
#[\Attribute(\Attribute::TARGET_METHOD)]
final readonly class Test$capture
public bool $capture__construct()
public function __construct(public bool $capture = true)Timeout
Namespace: Greenlight\Attribute
Fails an otherwise passed attempt if its run time exceeds the specified number of seconds. Greenlight checks elapsed time after per-test service disposal. This check does not interrupt PHP code that is still running. A class attribute applies the limit to each test in the class.
During process-pool execution, the orchestrator also stops a blocked worker after the timeout grace period. In-process execution has no such interrupt.
#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS)]
final readonly class Timeout$seconds
public float $seconds__construct()
public function __construct(
public float $seconds,
)PHPDoc:
@throws \InvalidArgumentException
ClassAvailable
Namespace: Greenlight\Condition
Passes when class_exists() finds the named class, with autoloading enabled.
final readonly class ClassAvailable implements Condition__construct()
public function __construct(string $class)PHPDoc:
@param non-empty-string $class@throws \InvalidArgumentException
isSatisfied()
public function isSatisfied(): boolCondition
Namespace: Greenlight\Condition
A runtime condition that #[SkipUnless] references.
Implementations can receive constructor arguments from #[SkipUnless].
Constructors must only store these arguments. isSatisfied() evaluates the
condition and must not cause other changes.
interface ConditionisSatisfied()
public function isSatisfied(): bool;EnvironmentVariableEquals
Namespace: Greenlight\Condition
Passes when getenv() returns the exact expected string for the variable.
final readonly class EnvironmentVariableEquals implements Condition__construct()
public function __construct(string $name, private string $value)PHPDoc:
@param non-empty-string $name@throws \InvalidArgumentException
isSatisfied()
public function isSatisfied(): boolEnvironmentVariableSet
Namespace: Greenlight\Condition
Passes when getenv() finds the variable, including an empty string value.
final readonly class EnvironmentVariableSet implements Condition__construct()
public function __construct(string $name)PHPDoc:
@param non-empty-string $name@throws \InvalidArgumentException
isSatisfied()
public function isSatisfied(): boolExtensionLoaded
Namespace: Greenlight\Condition
Passes when the named PHP extension is loaded.
final readonly class ExtensionLoaded implements Condition__construct()
public function __construct(string $extension)PHPDoc:
@param non-empty-string $extension@throws \InvalidArgumentException
isSatisfied()
public function isSatisfied(): boolExtensionMissing
Namespace: Greenlight\Condition
Passes when the named PHP extension is not loaded.
final readonly class ExtensionMissing implements Condition__construct()
public function __construct(string $extension)PHPDoc:
@param non-empty-string $extension@throws \InvalidArgumentException
isSatisfied()
public function isSatisfied(): boolFunctionAvailable
Namespace: Greenlight\Condition
Passes when function_exists() finds the named function.
final readonly class FunctionAvailable implements Condition__construct()
public function __construct(string $function)PHPDoc:
@param non-empty-string $function@throws \InvalidArgumentException
isSatisfied()
public function isSatisfied(): boolOperatingSystemFamily
Namespace: Greenlight\Condition
Compares the value to PHP_OS_FAMILY without case sensitivity.
final readonly class OperatingSystemFamily implements Condition__construct()
public function __construct(string $family)PHPDoc:
@param non-empty-string $family@throws \InvalidArgumentException
isSatisfied()
public function isSatisfied(): boolPhpVersionAtLeast
Namespace: Greenlight\Condition
Passes when PHP_VERSION is at least the specified version, as compared by version_compare().
final readonly class PhpVersionAtLeast implements Condition__construct()
public function __construct(string $version)PHPDoc:
@param non-empty-string $version@throws \InvalidArgumentException
isSatisfied()
public function isSatisfied(): boolPhpVersionLessThan
Namespace: Greenlight\Condition
Passes when PHP_VERSION is less than the specified version, as compared by version_compare().
final readonly class PhpVersionLessThan implements Condition__construct()
public function __construct(string $version)PHPDoc:
@param non-empty-string $version@throws \InvalidArgumentException
isSatisfied()
public function isSatisfied(): bool