Expectations API

This reference lists immediate and temporal expectation types.

These signatures are the public API.

`CallExpectation`

Namespace: Greenlight\Expect

Checks a call’s captured outcome. Construct with Expect::calling(). Matchers in one immediate chain share one invocation.

final class CallExpectation

View source

PHPDoc:

@template T

`not()`

public function not(): self

PHPDoc:

@return self<T>

View source

`because()`

Sets a reason for all subsequent matchers in the chain. Another because() call replaces the reason.

public function because(string $reason): self

PHPDoc:

@param non-empty-string $reason
@return self<T>
@throws ExpectationFailed

View source

`toReturn()`

Checks identity with the return value. An unexpected throwable propagates.

public function toReturn(mixed $expected): self

PHPDoc:

@return self<T>
@throws ExpectationFailed

View source

`returnValue()`

Selects the return value without invoking the call.

public function returnValue(): ReturnValueExpectation

PHPDoc:

@return ReturnValueExpectation<T>
@throws ExpectationFailed

View source

`toThrow()`

Checks the thrown type, exact object, or typed callback constraint. With no constraint, matches any Throwable.

public function toThrow(
    string|\Closure|\Throwable $throwable = \Throwable::class,
    ?string $matching = null,
    ?string $message = null,
): self

PHPDoc:

@template TThrowable of \Throwable
@param class-string<TThrowable>|TThrowable|\Closure(TThrowable): void $throwable
@return self<T>
@throws ExpectationFailed

View source

`eventually()`

public function eventually(): PendingEventuallyCall

PHPDoc:

@return PendingEventuallyCall<T>
@throws ExpectationFailed

View source

`consistently()`

public function consistently(): PendingConsistentlyCall

PHPDoc:

@return PendingConsistentlyCall<T>
@throws ExpectationFailed

View source

`ConsistentlyExpectation`

Namespace: Greenlight\Expect

Checks each probe value for a fixed period and fails on the first mismatch. Use Expect::calling(...)->returnValue()->consistently() and for() to create this object.

final class ConsistentlyExpectation extends TemporalExpectation

View source

PHPDoc:

@template T
@extends TemporalExpectation<T>

`toBe()`

Passes when the subject and expected value are identical (===).

public function toBe(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toEqual()`

Passes when the subject and expected value satisfy the rules for deep equality in the Expectation class description.

public function toEqual(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed
@throws \InvalidArgumentException when the comparison follows a cyclic array

View source

`toEqualCanonicalizing()`

Uses the toEqual() rules but ignores list-element order. Canonicalization recurses through array values. It does not inspect object properties. Thus, lists in object properties keep their order. Associative arrays keep their keys.

public function toEqualCanonicalizing(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed
@throws \InvalidArgumentException when an array selected for comparison or ordering contains a cycle

View source

`toBeOneOf()`

Passes when the subject is identical (===) to one of the options.

public function toBeOneOf(mixed ...$options): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeIn()`

Passes when the haystack contains the subject by identity (===). This matcher is the reverse of toContain(). The check consumes a Traversable haystack.

public function toBeIn(iterable $haystack): Expectation

PHPDoc:

@param iterable<mixed> $haystack
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeInstanceOf()`

public function toBeInstanceOf(string $class): Expectation

PHPDoc:

@param class-string $class
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeTrue()`

public function toBeTrue(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeFalse()`

public function toBeFalse(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeNull()`

public function toBeNull(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeArray()`

public function toBeArray(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeString()`

public function toBeString(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeInt()`

public function toBeInt(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeFloat()`

public function toBeFloat(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeBool()`

public function toBeBool(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeCallable()`

public function toBeCallable(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeIterable()`

public function toBeIterable(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toContain()`

For a string subject, checks for a string needle. For an iterable subject, checks for the value by identity (===). Iteration stops at the first match or the end of the subject.

public function toContain(mixed $needle): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveCount()`

Accepts an array, Countable, or Traversable subject. Uses count() for arrays and Countable objects. Otherwise, consumes the iterator.

public function toHaveCount(int $count): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeEmpty()`

Passes when the subject is an empty string or contains no elements. Accepts a string, array, Countable, or Traversable subject. Uses count() for arrays and Countable objects. For other Traversable objects, consumes the iterator.

public function toBeEmpty(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveLength()`

For a valid UTF-8 string, measures the number of code points. For other strings, measures the number of bytes. Array and Countable subjects use count().

public function toHaveLength(int $length): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveKey()`

The subject must be an array or an ArrayAccess implementation. The matcher uses array_key_exists() for arrays and offsetExists() for ArrayAccess.

public function toHaveKey(int|string $key): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toContainSubset()`

Each subset key must exist in the subject with an equal value. Equality uses the toEqual() rules. A nested array is also a subset. The related nested subject array can contain extra keys. The failure identifies the first different key by its dot-separated path.

public function toContainSubset(array $subset): Expectation

PHPDoc:

@param array<array-key, mixed> $subset
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeGreaterThan()`

public function toBeGreaterThan(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeGreaterThanOrEqual()`

public function toBeGreaterThanOrEqual(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeLessThan()`

public function toBeLessThan(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeLessThanOrEqual()`

public function toBeLessThanOrEqual(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeWithin()`

Passes when the absolute difference between the numeric subject and $of is not more than $delta. Use a finite tolerance of zero or more.

public function toBeWithin(float $delta, float $of): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toMatch()`

public function toMatch(string $pattern): Expectation

PHPDoc:

@return Expectation<T>
@throws \InvalidArgumentException when the pattern is not a valid regular expression
@throws ExpectationFailed

View source

`toStartWith()`

public function toStartWith(string $prefix): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toEndWith()`

public function toEndWith(string $suffix): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeJson()`

The subject must be a string. The matcher passes when the string contains valid JSON.

public function toBeJson(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toMatchJson()`

The subject must be a string that contains valid JSON. The matcher decodes the subject and expected JSON. It then applies deep equality to the results. Object-key order has no effect. Invalid subject JSON causes an expectation failure. Invalid expected JSON causes a usage error.

public function toMatchJson(string $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`not()`

Negates the next matcher for every value returned by the probe.

final public function not(): static

View source

`because()`

Sets a reason for all subsequent matchers in the chain. Another because() call replaces the reason.

If the matcher fails, the failure message ends with “because” and the reason. An empty reason causes a usage failure.

final public function because(string $reason): static

PHPDoc:

@param non-empty-string $reason
@throws ExpectationFailed

View source

`__call()`

Runs a native or configured extension matcher against each probe value.

final public function __call(string $name, array $arguments): Expectation

PHPDoc:

@param array<array-key, mixed> $arguments
@return Expectation<T>
@throws \BadMethodCallException if no native or registered extension matcher has the requested name
@throws ExpectationFailed

View source

`EventuallyExpectation`

Namespace: Greenlight\Expect

Polls the probe until its matcher passes or the deadline expires. Use Expect::calling(...)->returnValue()->eventually() and within() to create this object.

final class EventuallyExpectation extends TemporalExpectation

View source

PHPDoc:

@template T
@extends TemporalExpectation<T>

`toBe()`

Passes when the subject and expected value are identical (===).

public function toBe(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toEqual()`

Passes when the subject and expected value satisfy the rules for deep equality in the Expectation class description.

public function toEqual(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed
@throws \InvalidArgumentException when the comparison follows a cyclic array

View source

`toEqualCanonicalizing()`

public function toEqualCanonicalizing(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed
@throws \InvalidArgumentException when an array selected for comparison or ordering contains a cycle

View source

`toBeOneOf()`

Passes when the subject is identical (===) to one of the options.

public function toBeOneOf(mixed ...$options): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeIn()`

Passes when the haystack contains the subject by identity (===). This matcher is the reverse of toContain(). The check consumes a Traversable haystack.

public function toBeIn(iterable $haystack): Expectation

PHPDoc:

@param iterable<mixed> $haystack
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeInstanceOf()`

public function toBeInstanceOf(string $class): Expectation

PHPDoc:

@param class-string $class
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeTrue()`

public function toBeTrue(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeFalse()`

public function toBeFalse(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeNull()`

public function toBeNull(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeArray()`

public function toBeArray(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeString()`

public function toBeString(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeInt()`

public function toBeInt(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeFloat()`

public function toBeFloat(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeBool()`

public function toBeBool(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeCallable()`

public function toBeCallable(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeIterable()`

public function toBeIterable(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toContain()`

For a string subject, checks for a string needle. For an iterable subject, checks for the value by identity (===). Iteration stops at the first match or the end of the subject.

public function toContain(mixed $needle): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveCount()`

Accepts an array, Countable, or Traversable subject. Uses count() for arrays and Countable objects. Otherwise, consumes the iterator.

public function toHaveCount(int $count): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeEmpty()`

public function toBeEmpty(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveLength()`

For a valid UTF-8 string, measures the number of code points. For other strings, measures the number of bytes. Array and Countable subjects use count().

public function toHaveLength(int $length): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveKey()`

The subject must be an array or an ArrayAccess implementation. The matcher uses array_key_exists() for arrays and offsetExists() for ArrayAccess.

public function toHaveKey(int|string $key): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toContainSubset()`

public function toContainSubset(array $subset): Expectation

PHPDoc:

@param array<array-key, mixed> $subset
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeGreaterThan()`

public function toBeGreaterThan(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeGreaterThanOrEqual()`

public function toBeGreaterThanOrEqual(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeLessThan()`

public function toBeLessThan(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeLessThanOrEqual()`

public function toBeLessThanOrEqual(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeWithin()`

Passes when the absolute difference between the numeric subject and $of is not more than $delta. Use a finite tolerance of zero or more.

public function toBeWithin(float $delta, float $of): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toMatch()`

public function toMatch(string $pattern): Expectation

PHPDoc:

@return Expectation<T>
@throws \InvalidArgumentException when the pattern is not a valid regular expression
@throws ExpectationFailed

View source

`toStartWith()`

public function toStartWith(string $prefix): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toEndWith()`

public function toEndWith(string $suffix): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeJson()`

The subject must be a string. The matcher passes when the string contains valid JSON.

public function toBeJson(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toMatchJson()`

public function toMatchJson(string $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`not()`

Negates the next matcher for every value returned by the probe.

final public function not(): static

View source

`because()`

Sets a reason for all subsequent matchers in the chain. Another because() call replaces the reason.

If the matcher fails, the failure message ends with “because” and the reason. An empty reason causes a usage failure.

final public function because(string $reason): static

PHPDoc:

@param non-empty-string $reason
@throws ExpectationFailed

View source

`__call()`

Runs a native or configured extension matcher against each probe value.

final public function __call(string $name, array $arguments): Expectation

PHPDoc:

@param array<array-key, mixed> $arguments
@return Expectation<T>
@throws \BadMethodCallException if no native or registered extension matcher has the requested name
@throws ExpectationFailed

View source

`Expect`

Namespace: Greenlight\Expect

Creates immediate and temporal expectations.

The worker loads the configured expectation extensions before test execution. Each expectation chain uses a snapshot of those extensions. The runner also loads Greenlight\expect($value) for value expectations. Use Greenlight\expect()->calling($call) to select a call explicitly. Import the function for short expectation calls.

final class Expect

View source

`value()`

public static function value(mixed $value): Expectation

PHPDoc:

@template T
@param T $value
@return Expectation<T>

View source

`calling()`

Selects a call without executing it.

public static function calling(callable $call): CallExpectation

PHPDoc:

@template T
@param callable(): T $call
@return CallExpectation<T>

View source

`Expectation`

Namespace: Greenlight\Expect

Checks one value. Callable values are never invoked. Use Expect::value() to create an expectation.

toEqual() uses these rules for deep equality:

Integers and floats use numeric value. Thus, 1 equals 1.0. NAN does not equal a value, even itself.
Other scalar values and null use strict equality. Thus, '1' does not equal 1.
Arrays are equal when they contain the same keys and recursively equal values. Key order has no effect. Cyclic arrays are unsupported. When the comparison follows a cycle, it raises InvalidArgumentException.
Enum cases, closures, and resources use identity.
DateTimeInterface instances are equal at the same instant and microsecond. The timezone has no effect.
Other objects are equal when they have the same class and recursively equal properties. This rule includes private and inherited properties. The comparison safely processes cyclic object structures.

class Expectation

View source

PHPDoc:

@template T

`toBe()`

Passes when the subject and expected value are identical (===).

public function toBe(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toEqual()`

Passes when the subject and expected value satisfy the rules for deep equality in the Expectation class description.

public function toEqual(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed
@throws \InvalidArgumentException when the comparison follows a cyclic array

View source

`toEqualCanonicalizing()`

public function toEqualCanonicalizing(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed
@throws \InvalidArgumentException when an array selected for comparison or ordering contains a cycle

View source

`toBeOneOf()`

Passes when the subject is identical (===) to one of the options.

public function toBeOneOf(mixed ...$options): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeIn()`

Passes when the haystack contains the subject by identity (===). This matcher is the reverse of toContain(). The check consumes a Traversable haystack.

public function toBeIn(iterable $haystack): Expectation

PHPDoc:

@param iterable<mixed> $haystack
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeInstanceOf()`

public function toBeInstanceOf(string $class): Expectation

PHPDoc:

@param class-string $class
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeTrue()`

public function toBeTrue(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeFalse()`

public function toBeFalse(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeNull()`

public function toBeNull(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeArray()`

public function toBeArray(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeString()`

public function toBeString(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeInt()`

public function toBeInt(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeFloat()`

public function toBeFloat(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeBool()`

public function toBeBool(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeCallable()`

public function toBeCallable(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeIterable()`

public function toBeIterable(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toContain()`

For a string subject, checks for a string needle. For an iterable subject, checks for the value by identity (===). Iteration stops at the first match or the end of the subject.

public function toContain(mixed $needle): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveCount()`

Accepts an array, Countable, or Traversable subject. Uses count() for arrays and Countable objects. Otherwise, consumes the iterator.

public function toHaveCount(int $count): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeEmpty()`

public function toBeEmpty(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveLength()`

For a valid UTF-8 string, measures the number of code points. For other strings, measures the number of bytes. Array and Countable subjects use count().

public function toHaveLength(int $length): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveKey()`

The subject must be an array or an ArrayAccess implementation. The matcher uses array_key_exists() for arrays and offsetExists() for ArrayAccess.

public function toHaveKey(int|string $key): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toContainSubset()`

public function toContainSubset(array $subset): Expectation

PHPDoc:

@param array<array-key, mixed> $subset
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeGreaterThan()`

public function toBeGreaterThan(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeGreaterThanOrEqual()`

public function toBeGreaterThanOrEqual(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeLessThan()`

public function toBeLessThan(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeLessThanOrEqual()`

public function toBeLessThanOrEqual(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeWithin()`

Passes when the absolute difference between the numeric subject and $of is not more than $delta. Use a finite tolerance of zero or more.

public function toBeWithin(float $delta, float $of): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toMatch()`

public function toMatch(string $pattern): Expectation

PHPDoc:

@return Expectation<T>
@throws \InvalidArgumentException when the pattern is not a valid regular expression
@throws ExpectationFailed

View source

`toStartWith()`

public function toStartWith(string $prefix): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toEndWith()`

public function toEndWith(string $suffix): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeJson()`

The subject must be a string. The matcher passes when the string contains valid JSON.

public function toBeJson(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toMatchJson()`

public function toMatchJson(string $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`not()`

public function not(): static

View source

`because()`

Sets a reason for all subsequent matchers in the chain. Another because() call replaces the reason.

public function because(string $reason): static

PHPDoc:

@param non-empty-string $reason
@throws ExpectationFailed

View source

`__call()`

public function __call(string $name, array $arguments): Expectation

PHPDoc:

@param array<array-key, mixed> $arguments
@return Expectation<T>
@throws \BadMethodCallException
@throws ExpectationFailed

View source

`ExpectationBuilder`

Namespace: Greenlight\Expect

Selects an explicit call subject after Greenlight\expect() with no argument.

final readonly class ExpectationBuilder

View source

`calling()`

Selects a call for later execution.

public function calling(callable $call): CallExpectation

PHPDoc:

@template T
@param callable(): T $call
@return CallExpectation<T>

View source

`ExpectationExtension`

Namespace: Greenlight\Expect

Supplies extension matchers through Expectation::__call().

interface ExpectationExtension extends Plugin

View source

`matchers()`

Maps each expectation-chain matcher name to its predicate.

Names must not match public native expectation methods. The comparison ignores letter case. Rename a matcher that has a conflicting name.

The predicate receives the subject and then the matcher arguments. Native parameter types declare the arguments. The predicate must return true for the expectation to hold. All other results fail it. Each matcher can use narrower parameters. Thus, one closure signature cannot describe all matchers.

public function matchers(): array;

PHPDoc:

@return array<non-empty-string, \Closure>

View source

`ExpectationFailed`

Namespace: Greenlight\Expect

Identifies one or more failed expectations.

Contains structured FailureDetail values. The runner uses them to report the expected value, actual value, and call site. It does not have to parse the message.

final class ExpectationFailed extends \Exception

View source

`$details`

public readonly array $details

View source

`fromDetail()`

public static function fromDetail(FailureDetail $detail): self

View source

`fromDetails()`

public static function fromDetails(array $details): self

PHPDoc:

@param non-empty-list<FailureDetail> $details

View source

`detail()`

Returns the first failure. Use $details to read all failures, including multiple unmet mock expectations.

public function detail(): FailureDetail

View source

`Fail`

Namespace: Greenlight\Expect

final class Fail

View source

`because()`

public static function because(string $reason): never

PHPDoc:

@throws ExpectationFailed

View source

`PendingConsistently`

Namespace: Greenlight\Expect

Collects poll options until for() sets the duration. Use Expect::calling(...)->returnValue()->consistently() to create this object.

final class PendingConsistently

View source

PHPDoc:

@template T

`not()`

public function not(): self

PHPDoc:

@return self<T>

View source

`because()`

public function because(string $reason): self

PHPDoc:

@param non-empty-string $reason
@return self<T>
@throws ExpectationFailed

View source

`pollEvery()`

public function pollEvery(float $seconds): self

PHPDoc:

@return self<T>
@throws \InvalidArgumentException if the interval is not finite or is less than 0.001 seconds

View source

`for()`

public function for(float $seconds): ConsistentlyExpectation

PHPDoc:

@throws ExpectationFailed
@return ConsistentlyExpectation<T>
@throws \InvalidArgumentException if the duration is not finite or is not positive

View source

`PendingConsistentlyCall`

Namespace: Greenlight\Expect

Collects time controls for a call expectation.

final readonly class PendingConsistentlyCall

View source

PHPDoc:

@template T

`not()`

public function not(): self

PHPDoc:

@return self<T>

View source

`because()`

public function because(string $reason): self

PHPDoc:

@param non-empty-string $reason
@return self<T>
@throws ExpectationFailed

View source

`pollEvery()`

public function pollEvery(float $seconds): self

PHPDoc:

@return self<T>

View source

`for()`

public function for(float $seconds): TemporalCallExpectation

PHPDoc:

@return TemporalCallExpectation<T>
@throws ExpectationFailed

View source

`PendingEventually`

Namespace: Greenlight\Expect

Collects poll options until within() sets the deadline. Use Expect::calling(...)->returnValue()->eventually() to create this object.

final class PendingEventually

View source

PHPDoc:

@template T

`not()`

public function not(): self

PHPDoc:

@return self<T>

View source

`because()`

public function because(string $reason): self

PHPDoc:

@param non-empty-string $reason
@return self<T>
@throws ExpectationFailed

View source

`pollEvery()`

public function pollEvery(float $seconds): self

PHPDoc:

@return self<T>
@throws \InvalidArgumentException if the interval is not finite or is less than 0.001 seconds

View source

`retryOnException()`

public function retryOnException(string ...$types): self

PHPDoc:

@param class-string<\Exception> ...$types
@return self<T>
@throws \InvalidArgumentException if a type does not extend Exception

View source

`within()`

public function within(float $seconds): EventuallyExpectation

PHPDoc:

@throws ExpectationFailed
@return EventuallyExpectation<T>
@throws \InvalidArgumentException if the duration is not finite or is not positive

View source

`PendingEventuallyCall`

Namespace: Greenlight\Expect

Collects time controls for a call expectation.

final readonly class PendingEventuallyCall

View source

PHPDoc:

@template T

`not()`

public function not(): self

PHPDoc:

@return self<T>

View source

`because()`

public function because(string $reason): self

PHPDoc:

@param non-empty-string $reason
@return self<T>
@throws ExpectationFailed

View source

`pollEvery()`

public function pollEvery(float $seconds): self

PHPDoc:

@return self<T>

View source

`within()`

public function within(float $seconds): TemporalCallExpectation

PHPDoc:

@return TemporalCallExpectation<T>
@throws ExpectationFailed

View source

`ReturnValueExpectation`

Namespace: Greenlight\Expect

Checks a call’s return value immediately or over time. A temporal matcher invokes the original call once per observation.

final class ReturnValueExpectation extends Expectation

View source

PHPDoc:

@template T
@extends Expectation<T>

`toBe()`

Passes when the subject and expected value are identical (===).

public function toBe(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toEqual()`

Passes when the subject and expected value satisfy the rules for deep equality in the Expectation class description.

public function toEqual(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed
@throws \InvalidArgumentException when the comparison follows a cyclic array

View source

`toEqualCanonicalizing()`

public function toEqualCanonicalizing(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed
@throws \InvalidArgumentException when an array selected for comparison or ordering contains a cycle

View source

`toBeOneOf()`

Passes when the subject is identical (===) to one of the options.

public function toBeOneOf(mixed ...$options): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeIn()`

Passes when the haystack contains the subject by identity (===). This matcher is the reverse of toContain(). The check consumes a Traversable haystack.

public function toBeIn(iterable $haystack): Expectation

PHPDoc:

@param iterable<mixed> $haystack
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeInstanceOf()`

public function toBeInstanceOf(string $class): Expectation

PHPDoc:

@param class-string $class
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeTrue()`

public function toBeTrue(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeFalse()`

public function toBeFalse(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeNull()`

public function toBeNull(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeArray()`

public function toBeArray(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeString()`

public function toBeString(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeInt()`

public function toBeInt(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeFloat()`

public function toBeFloat(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeBool()`

public function toBeBool(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeCallable()`

public function toBeCallable(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeIterable()`

public function toBeIterable(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toContain()`

For a string subject, checks for a string needle. For an iterable subject, checks for the value by identity (===). Iteration stops at the first match or the end of the subject.

public function toContain(mixed $needle): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveCount()`

Accepts an array, Countable, or Traversable subject. Uses count() for arrays and Countable objects. Otherwise, consumes the iterator.

public function toHaveCount(int $count): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeEmpty()`

public function toBeEmpty(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveLength()`

For a valid UTF-8 string, measures the number of code points. For other strings, measures the number of bytes. Array and Countable subjects use count().

public function toHaveLength(int $length): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveKey()`

The subject must be an array or an ArrayAccess implementation. The matcher uses array_key_exists() for arrays and offsetExists() for ArrayAccess.

public function toHaveKey(int|string $key): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toContainSubset()`

public function toContainSubset(array $subset): Expectation

PHPDoc:

@param array<array-key, mixed> $subset
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeGreaterThan()`

public function toBeGreaterThan(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeGreaterThanOrEqual()`

public function toBeGreaterThanOrEqual(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeLessThan()`

public function toBeLessThan(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeLessThanOrEqual()`

public function toBeLessThanOrEqual(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeWithin()`

Passes when the absolute difference between the numeric subject and $of is not more than $delta. Use a finite tolerance of zero or more.

public function toBeWithin(float $delta, float $of): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toMatch()`

public function toMatch(string $pattern): Expectation

PHPDoc:

@return Expectation<T>
@throws \InvalidArgumentException when the pattern is not a valid regular expression
@throws ExpectationFailed

View source

`toStartWith()`

public function toStartWith(string $prefix): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toEndWith()`

public function toEndWith(string $suffix): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeJson()`

The subject must be a string. The matcher passes when the string contains valid JSON.

public function toBeJson(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toMatchJson()`

public function toMatchJson(string $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`not()`

public function not(): static

View source

`because()`

Sets a reason for all subsequent matchers in the chain. Another because() call replaces the reason.

public function because(string $reason): static

PHPDoc:

@param non-empty-string $reason
@throws ExpectationFailed

View source

`__call()`

public function __call(string $name, array $arguments): Expectation

PHPDoc:

@param array<array-key, mixed> $arguments
@return Expectation<T>
@throws \BadMethodCallException
@throws ExpectationFailed

View source

`eventually()`

public function eventually(): PendingEventually

PHPDoc:

@return PendingEventually<T>
@throws ExpectationFailed

View source

`consistently()`

public function consistently(): PendingConsistently

PHPDoc:

@return PendingConsistently<T>
@throws ExpectationFailed

View source

`TemporalCallExpectation`

Namespace: Greenlight\Expect

Checks a call outcome on each poll and retains the last matched outcome.

final readonly class TemporalCallExpectation

View source

PHPDoc:

@template T

`not()`

public function not(): self

PHPDoc:

@return self<T>

View source

`because()`

public function because(string $reason): self

PHPDoc:

@param non-empty-string $reason
@return self<T>
@throws ExpectationFailed

View source

`toReturn()`

public function toReturn(mixed $expected): CallExpectation

PHPDoc:

@return CallExpectation<T>
@throws ExpectationFailed

View source

`toThrow()`

public function toThrow(
    string|\Closure|\Throwable $throwable = \Throwable::class,
    ?string $matching = null,
    ?string $message = null,
): CallExpectation

PHPDoc:

@template TThrowable of \Throwable
@param class-string<TThrowable>|TThrowable|\Closure(TThrowable): void $throwable
@return CallExpectation<T>
@throws ExpectationFailed

View source

`TemporalExpectation`

Namespace: Greenlight\Expect

Contains the matcher dispatch and probe operations for eventual and consistent expectations.

abstract class TemporalExpectation

View source

PHPDoc:

@template T

`toBe()`

Passes when the subject and expected value are identical (===).

public function toBe(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toEqual()`

Passes when the subject and expected value satisfy the rules for deep equality in the Expectation class description.

public function toEqual(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed
@throws \InvalidArgumentException when the comparison follows a cyclic array

View source

`toEqualCanonicalizing()`

public function toEqualCanonicalizing(mixed $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed
@throws \InvalidArgumentException when an array selected for comparison or ordering contains a cycle

View source

`toBeOneOf()`

Passes when the subject is identical (===) to one of the options.

public function toBeOneOf(mixed ...$options): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeIn()`

Passes when the haystack contains the subject by identity (===). This matcher is the reverse of toContain(). The check consumes a Traversable haystack.

public function toBeIn(iterable $haystack): Expectation

PHPDoc:

@param iterable<mixed> $haystack
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeInstanceOf()`

public function toBeInstanceOf(string $class): Expectation

PHPDoc:

@param class-string $class
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeTrue()`

public function toBeTrue(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeFalse()`

public function toBeFalse(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeNull()`

public function toBeNull(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeArray()`

public function toBeArray(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeString()`

public function toBeString(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeInt()`

public function toBeInt(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeFloat()`

public function toBeFloat(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeBool()`

public function toBeBool(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeCallable()`

public function toBeCallable(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeIterable()`

public function toBeIterable(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toContain()`

For a string subject, checks for a string needle. For an iterable subject, checks for the value by identity (===). Iteration stops at the first match or the end of the subject.

public function toContain(mixed $needle): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveCount()`

Accepts an array, Countable, or Traversable subject. Uses count() for arrays and Countable objects. Otherwise, consumes the iterator.

public function toHaveCount(int $count): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeEmpty()`

public function toBeEmpty(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveLength()`

For a valid UTF-8 string, measures the number of code points. For other strings, measures the number of bytes. Array and Countable subjects use count().

public function toHaveLength(int $length): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toHaveKey()`

The subject must be an array or an ArrayAccess implementation. The matcher uses array_key_exists() for arrays and offsetExists() for ArrayAccess.

public function toHaveKey(int|string $key): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toContainSubset()`

public function toContainSubset(array $subset): Expectation

PHPDoc:

@param array<array-key, mixed> $subset
@return Expectation<T>
@throws ExpectationFailed

View source

`toBeGreaterThan()`

public function toBeGreaterThan(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeGreaterThanOrEqual()`

public function toBeGreaterThanOrEqual(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeLessThan()`

public function toBeLessThan(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeLessThanOrEqual()`

public function toBeLessThanOrEqual(int|float $bound): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeWithin()`

Passes when the absolute difference between the numeric subject and $of is not more than $delta. Use a finite tolerance of zero or more.

public function toBeWithin(float $delta, float $of): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toMatch()`

public function toMatch(string $pattern): Expectation

PHPDoc:

@return Expectation<T>
@throws \InvalidArgumentException when the pattern is not a valid regular expression
@throws ExpectationFailed

View source

`toStartWith()`

public function toStartWith(string $prefix): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toEndWith()`

public function toEndWith(string $suffix): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toBeJson()`

The subject must be a string. The matcher passes when the string contains valid JSON.

public function toBeJson(): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`toMatchJson()`

public function toMatchJson(string $expected): Expectation

PHPDoc:

@return Expectation<T>
@throws ExpectationFailed

View source

`not()`

Negates the next matcher for every value returned by the probe.

final public function not(): static

View source

`because()`

Sets a reason for all subsequent matchers in the chain. Another because() call replaces the reason.

If the matcher fails, the failure message ends with “because” and the reason. An empty reason causes a usage failure.

final public function because(string $reason): static

PHPDoc:

@param non-empty-string $reason
@throws ExpectationFailed

View source

`__call()`

Runs a native or configured extension matcher against each probe value.

final public function __call(string $name, array $arguments): Expectation

PHPDoc:

@param array<array-key, mixed> $arguments
@return Expectation<T>
@throws \BadMethodCallException if no native or registered extension matcher has the requested name
@throws ExpectationFailed

View source