Test contracts API

This reference lists test definitions, policies, and skip signals.

These signatures are the public API.

`Cleanup`

Namespace: Greenlight\Test

Stores cleanup callbacks for one test attempt. Greenlight runs the callbacks in reverse registration order after the After hooks. Per-test service disposal starts after the callbacks finish.

Greenlight runs all callbacks if one fails. An expectation failure during cleanup fails a passed or skipped test. Other cleanup exceptions cause an errored result. Cleanup does not replace an earlier test failure or error.

final class Cleanup

`defer()`

Register cleanup immediately after the test acquires a resource. This makes cleanup available if a later operation fails. Greenlight ignores the callback return value.

public function defer(\Closure $cleanup): void

PHPDoc:

@template TReturn
@param \Closure(): TReturn $cleanup
@throws \LogicException If test cleanup has started.

`DataProvider`

Namespace: Greenlight\Test

Identifies the method and optional external class that supply test data sets.

final readonly class DataProvider

`$method`

public ?string $method

`$class`

public ?string $class

`__construct()`

public function __construct(
    public ?string $method = null,
    public ?string $class = null,
)

PHPDoc:

@param non-empty-string|null $method
@param non-empty-string|null $class
@throws \InvalidArgumentException

`ExecutionPolicy`

Namespace: Greenlight\Test

Defines timeout, output capture, and expectation rules for one test.

final readonly class ExecutionPolicy

`$timeoutSeconds`

public ?float $timeoutSeconds

`$capture`

public bool $capture

`$noExpectations`

public bool $noExpectations

`__construct()`

public function __construct(
    public ?float $timeoutSeconds = null,
    public bool $capture = true,
    public bool $noExpectations = false,
)

PHPDoc:

@throws \InvalidArgumentException

`RetryPolicy`

Namespace: Greenlight\Test

Defines the retry limit and the optional throwable filter for a test.

final readonly class RetryPolicy

`$times`

public ?int $times;

PHPDoc:

@var positive-int|null

`$onlyOn`

public ?string $onlyOn

`__construct()`

public function __construct(
    ?int $times = null,
    public ?string $onlyOn = null,
)

PHPDoc:

@param non-empty-string|null $onlyOn
@throws \InvalidArgumentException

`SchedulingPolicy`

Namespace: Greenlight\Test

Defines worker assignment and resource rules for one test.

final readonly class SchedulingPolicy

`$resources`

public array $resources;

PHPDoc:

@var list<non-empty-string>

`$isolated`

public bool $isolated

`$allowParallel`

public bool $allowParallel

`__construct()`

public function __construct(
    public bool $isolated = false,
    array $resources = [],
    public bool $allowParallel = false,
)

PHPDoc:

@param list<string> $resources named resources required by this test
@throws \InvalidArgumentException

`SkipPolicy`

Namespace: Greenlight\Test

Defines the static reason or condition that skips a test.

final readonly class SkipPolicy

`$arguments`

public array $arguments;

PHPDoc:

@var list<scalar|null>

`$reason`

public ?string $reason

`$condition`

public ?string $condition

`__construct()`

public function __construct(
    public ?string $reason = null,
    public ?string $condition = null,
    array $arguments = [],
)

PHPDoc:

@param non-empty-string|null $reason
@param non-empty-string|null $condition
@param list<mixed> $arguments validated to scalars or null
@throws \InvalidArgumentException

`SkipTest`

Namespace: Greenlight\Test

Reports a skipped test with the specified reason.

Throw this signal from a test method, a before hook, or a beforeTest() subscriber.

final class SkipTest extends \Exception

`$reason`

public readonly string $reason;

PHPDoc:

@var non-empty-string

`__construct()`

public function __construct(string $reason)

PHPDoc:

@throws \InvalidArgumentException If $reason is empty.

`TestChannel`

Namespace: Greenlight\Test

A live worker owns a unique channel from 1 to the worker count. A replacement worker reuses a free channel. Thus, channel resources remain available when Greenlight replaces a worker. In-process runs use channel 1.

GREENLIGHT_CHANNEL supplies the same value outside the harness. label() adds “gl-” before the number.

final readonly class TestChannel

`$number`

public int $number;

PHPDoc:

@var positive-int

`__construct()`

public function __construct(int $number)

PHPDoc:

@throws \InvalidArgumentException

`label()`

public function label(): string

PHPDoc:

@return non-empty-string

`TestDefinition`

Namespace: Greenlight\Test

Contains one test declaration and its discovery policies.

final readonly class TestDefinition

`$class`

public string $class;

PHPDoc:

@var non-empty-string

`$method`

public string $method;

PHPDoc:

@var non-empty-string

`$groups`

public array $groups;

PHPDoc:

@var list<non-empty-string>

`$skip`

public SkipPolicy $skip

`$retry`

public RetryPolicy $retry

`$dataProvider`

public DataProvider $dataProvider

`$execution`

public ExecutionPolicy $execution

`$scheduling`

public SchedulingPolicy $scheduling

`__construct()`

public function __construct(
    string $class,
    string $method,
    array $groups = [],
    public SkipPolicy $skip = new SkipPolicy(),
    public RetryPolicy $retry = new RetryPolicy(),
    public DataProvider $dataProvider = new DataProvider(),
    public ExecutionPolicy $execution = new ExecutionPolicy(),
    public SchedulingPolicy $scheduling = new SchedulingPolicy(),
)

PHPDoc:

@param list<string> $groups
@throws \InvalidArgumentException

`TestId`

Namespace: Greenlight\Test

Identifies a test across processes for assignment, rerun selection, and the timing cache.

final readonly class TestId implements \Stringable

`$class`

public string $class;

PHPDoc:

@var non-empty-string

`$method`

public string $method;

PHPDoc:

@var non-empty-string

`$dataSetKey`

public ?string $dataSetKey

`__construct()`

public function __construct(
    string $class,
    string $method,
    public ?string $dataSetKey = null,
)

PHPDoc:

@throws \InvalidArgumentException

`equals()`

public function equals(self $other): bool

`__toString()`

public function __toString(): string