Plugin API
This reference lists plugin capabilities and lifecycle callback contracts.
These signatures are the public API.
HarnessProvider
Namespace: Greenlight\Plugin
Adds harness services to the worker registry.
Greenlight adds built-in services before services() results. A duplicate
type causes a configuration error.
interface HarnessProvider extends Pluginservices()
public function services(): array;PHPDoc:
@return list<ServiceDefinition>
Plugin
Namespace: Greenlight\Plugin
Identifies an object as a Greenlight plugin.
Plugins implement one or more capability interfaces such as
TestLifecycleSubscriber, RunLifecycleSubscriber, RetryDecider,
HarnessProvider, or ExpectationExtension.
interface PluginThis type does not declare public members.
Prioritized
Namespace: Greenlight\Plugin
Controls order within each plugin capability. Lower values run earlier. The default value is zero. Equal values keep their original order.
interface Prioritizedpriority()
public function priority(): int;RetryDecider
Namespace: Greenlight\Plugin
A worker calls a retry decider after each unsuccessful attempt.
A true result starts a new attempt with a new test instance and a new
service scope.
shouldRetry() receives the metadata, result, attempt number, and optional
cause. It does not receive TestContext because the attempt is complete.
interface RetryDecider extends PluginshouldRetry()
public function shouldRetry(TestMetadata $metadata, TestResult $result, int $attempt, ?\Throwable $cause): bool;RunLifecycleSubscriber
Namespace: Greenlight\Plugin
Observes the orchestrator event stream.
onRunEvent() receives run, worker, suite, class, and test events in the
order that they arrive.
The subscriber only observes events and cannot change results.
interface RunLifecycleSubscriber extends PluginonRunEvent()
public function onRunEvent(Event $event): void;TestContext
Namespace: Greenlight\Plugin
service() is available during beforeTest() and the test. The per-test
service scope closes before afterTest(), so service() throws during
afterTest().
final readonly class TestContext$attachments
public Attachments $attachments;service()
public function service(string $type): objectPHPDoc:
@template T of object@param class-string<T> $type@return T@throws UnresolvableService
skip()
Stops the current attempt during beforeTest(). Code after the call does
not run.
public function skip(string $reason): neverPHPDoc:
@param non-empty-string $reason@throws SkipTest
TestLifecycleSubscriber
Namespace: Greenlight\Plugin
Lets a plugin act before and after each test attempt in a worker.
afterTest() receives and returns the result. A plugin can return an
unchanged result or a replacement result. Use TestResult::withOutcome() for
outcome changes so that the result records their source.
interface TestLifecycleSubscriber extends PluginbeforeTest()
Greenlight calls beforeTest() after it constructs the test instance and
before the before hooks. $context->skip() or SkipTest reports a skipped
test. Greenlight reports other throwables as errors and names this
plugin in each error.
public function beforeTest(TestContext $context): void;PHPDoc:
@throws SkipTest
afterTest()
public function afterTest(TestContext $context, TestResult $result): TestResult;