Expectations API
This reference lists immediate and temporal expectation types.
These signatures are the public API.
ConsistentlyExpectation
Namespace: Greenlight\Expect
Checks each probe value for a fixed period and fails on the first mismatch.
final class ConsistentlyExpectation extends TemporalExpectationPHPDoc:
@template T@extends TemporalExpectation<T>
This type does not declare public members.
EventuallyExpectation
Namespace: Greenlight\Expect
Polls the probe until its matcher passes or the deadline expires.
final class EventuallyExpectation extends TemporalExpectationPHPDoc:
@template T@extends TemporalExpectation<T>
This type does not declare public members.
Expect
Namespace: Greenlight\Expect
Extension matchers are worker-local state. install() stores the configured
ExpectationExtension list when the worker starts. Each chain from that()
uses a snapshot of this list. The runner changes the list before test
execution starts. Before install() runs, that() uses no extensions.
final class Expectthat()
public static function that(mixed $value): ExpectationPHPDoc:
@template T@param T $value@return Expectation<T>
eventually()
Polls the probe until its matcher passes or the deadline expires.
public static function eventually(callable $probe): PendingEventuallyPHPDoc:
@template T@param callable(): T $probe@return PendingEventually<T>
consistently()
Polls the probe for a fixed period and fails on the first mismatch.
public static function consistently(callable $probe): PendingConsistentlyPHPDoc:
@template T@param callable(): T $probe@return PendingConsistently<T>
Expectation
Namespace: Greenlight\Expect
A fluent matcher chain for one subject value.
Use Expect::that() to create an instance.
A failed matcher throws ExpectationFailed immediately.
toEqual() uses these rules for deep equality:
-
Integers and floats use numeric value. Thus,
1equals1.0.NANdoes not equal a value, even itself. -
Other scalar values and
nulluse strict equality. Thus,'1'does not equal1. -
Arrays are equal when they contain the same keys and recursively equal values. Key order has no effect.
-
Enum cases, closures, and resources use identity.
-
DateTimeInterfaceinstances 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 structures.
final class ExpectationPHPDoc:
@template T
__call()
Dispatches extension matchers. If an ExpectationExtension provides the
requested matcher, this method gives it the subject and arguments.
An extension cannot replace a native matcher. PHP calls the native method directly.
public function __call(string $name, array $arguments): selfPHPDoc:
@param array<int, mixed> $arguments@return self<T>@throws ExpectationFailed
not()
Inverts the next matcher in the chain. That matcher consumes the inversion. Negation does not apply to subject type checks. A matcher fails if it cannot process the subject type.
public function not(): selfPHPDoc:
@return self<T>
because()
Sets a reason for the next matcher in the chain. The next matcher consumes the reason.
If the matcher fails, the failure message ends with “because” and the reason. An empty reason causes a usage failure.
public function because(string $reason): selfPHPDoc:
@param non-empty-string $reason@return self<T>@throws ExpectationFailed
and()
Sets a new subject for the chain. The chain does not apply not() and
because() modifiers to the new subject.
public function and(mixed $value): selfPHPDoc:
@template TNext@param TNext $value@return self<TNext>
toBe()
Passes when the subject and expected value are identical (===).
public function toBe(mixed $expected): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toEqual()
Passes when the subject and expected value satisfy the rules for deep equality on this class.
public function toEqual(mixed $expected): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toEqualCanonicalizing()
Uses the toEqual() rules but ignores list-element order at all levels.
Associative arrays keep their keys.
public function toEqualCanonicalizing(mixed $expected): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeOneOf()
Passes when the subject is identical (===) to one of the options.
public function toBeOneOf(mixed ...$options): selfPHPDoc:
@return self<T>@throws ExpectationFailed
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): selfPHPDoc:
@param iterable<mixed> $haystack@return self<T>@throws ExpectationFailed
toBeInstanceOf()
public function toBeInstanceOf(string $class): selfPHPDoc:
@param class-string $class@return self<T>@throws ExpectationFailed
toBeTrue()
public function toBeTrue(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeFalse()
public function toBeFalse(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeNull()
public function toBeNull(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeArray()
public function toBeArray(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeString()
public function toBeString(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeInt()
public function toBeInt(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeFloat()
public function toBeFloat(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeBool()
public function toBeBool(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeCallable()
public function toBeCallable(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeIterable()
public function toBeIterable(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toContain()
For a string subject, checks for a string needle. For an iterable
subject, checks for the value by identity (===). The check consumes a
Traversable subject.
public function toContain(mixed $needle): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toHaveCount()
The subject must be Countable or Traversable. The count consumes a
Traversable subject.
public function toHaveCount(int $count): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeEmpty()
Passes when the subject is an empty string or contains no elements.
The subject must be a string, array, Countable, or iterable. The check
consumes a Traversable subject.
public function toBeEmpty(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
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): selfPHPDoc:
@return self<T>@throws ExpectationFailed
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): selfPHPDoc:
@return self<T>@throws ExpectationFailed
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): selfPHPDoc:
@param array<array-key, mixed> $subset@return self<T>@throws ExpectationFailed
toBeGreaterThan()
public function toBeGreaterThan(int|float $bound): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeGreaterThanOrEqual()
public function toBeGreaterThanOrEqual(int|float $bound): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeLessThan()
public function toBeLessThan(int|float $bound): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeLessThanOrEqual()
public function toBeLessThanOrEqual(int|float $bound): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeWithin()
Passes when the absolute difference between the numeric subject and
$of is not more than $delta.
public function toBeWithin(float $delta, float $of): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toMatch()
public function toMatch(string $pattern): selfPHPDoc:
@return self<T>@throws \InvalidArgumentException when the pattern is not a valid regular expression@throws ExpectationFailed
toStartWith()
public function toStartWith(string $prefix): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toEndWith()
public function toEndWith(string $suffix): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toBeJson()
The subject must be a string. The matcher passes when the string contains valid JSON.
public function toBeJson(): selfPHPDoc:
@return self<T>@throws ExpectationFailed
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): selfPHPDoc:
@return self<T>@throws ExpectationFailed
toThrow()
The subject must be callable. The matcher calls it with no arguments. It passes when the subject throws an instance of the specified class. The message must satisfy the optional regular expression or exact-text constraint.
With not(), a throwable that does not satisfy both conditions makes the
matcher pass.
public function toThrow(string $throwable, ?string $matching = null, ?string $message = null): selfPHPDoc:
@param class-string<\Throwable> $throwable@return self<T>@throws \InvalidArgumentException when the match pattern is not a valid regular expression@throws ExpectationFailed
ExpectationExtension
Namespace: Greenlight\Expect
Supplies extension matchers through Expectation::__call().
interface ExpectationExtension extends Pluginmatchers()
Maps each expectation-chain matcher name to its predicate.
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>
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 \ExceptionfromDetail()
public static function fromDetail(FailureDetail $detail): selffromDetails()
public static function fromDetails(array $details): selfPHPDoc:
@param non-empty-list<FailureDetail> $details
detail()
Returns the first failure. In the default mode, this is the only failure.
public function detail(): FailureDetailFail
Namespace: Greenlight\Expect
final class Failbecause()
public static function because(string $reason): neverPHPDoc:
@throws ExpectationFailed
PendingConsistently
Namespace: Greenlight\Expect
Collects poll options until for() sets the duration.
final class PendingConsistentlyPHPDoc:
@template T
pollEvery()
public function pollEvery(float $seconds): selfPHPDoc:
@return self<T>
for()
public function for(float $seconds): ConsistentlyExpectationPHPDoc:
@return ConsistentlyExpectation<T>
PendingEventually
Namespace: Greenlight\Expect
Collects poll options until within() sets the deadline.
final class PendingEventuallyPHPDoc:
@template T
pollEvery()
public function pollEvery(float $seconds): selfPHPDoc:
@return self<T>
retryOnException()
public function retryOnException(string ...$types): selfPHPDoc:
@param class-string<\Exception> ...$types@return self<T>
within()
public function within(float $seconds): EventuallyExpectationPHPDoc:
@return EventuallyExpectation<T>