Doubles API
This reference lists double factories, argument matchers, captors, and mock plans.
These signatures are the public API.
Argument
Namespace: Greenlight\Doubles
final class Argumentany()
This matcher accepts all values in its position.
public static function any(): ArgumentMatchertype()
This matcher accepts instances of the specified class or interface.
It also accepts values when get_debug_type() returns $type.
public static function type(string $type): ArgumentMatcherPHPDoc:
@template TType of string@param TType $type@return ( $type is 'array' ? ArgumentMatcher<array<array-key, mixed>> : ( $type is 'bool' ? ArgumentMatcher<bool> : ( $type is 'float' ? ArgumentMatcher<float> : ( $type is 'int' ? ArgumentMatcher<int> : ( $type is 'null' ? ArgumentMatcher<null> : ( $type is 'string' ? ArgumentMatcher<string> : ( $type is class-string ? ArgumentMatcher<new<TType>> : ArgumentMatcher<mixed> ) ) ) ) ) ) )@throws InvalidDoubleUsage
intersection()
This matcher accepts values that have every specified type.
public static function intersection(string $first, string $second, string ...$rest): ArgumentMatcherPHPDoc:
@return ArgumentMatcher<mixed>@throws InvalidDoubleUsage
union()
This matcher accepts values that have one or more specified types.
public static function union(string $first, string $second, string ...$rest): ArgumentMatcherPHPDoc:
@return ArgumentMatcher<mixed>@throws InvalidDoubleUsage
predicate()
This matcher accepts the value when the closure returns true. A declared parameter type rejects incompatible values before the closure runs. The description identifies the constraint in failure messages.
public static function predicate(\Closure $predicate, string $description = 'predicate'): ArgumentMatcherPHPDoc:
@template T@param \Closure(T): mixed $predicate@return ArgumentMatcher<T>@throws InvalidDoubleUsage
equals()
This matcher uses the same deep equality as Expectation::toEqual().
Use it when with() must compare by value instead of identity.
public static function equals(mixed $value): ArgumentMatcherPHPDoc:
@template T@param T $value@return ArgumentMatcher<T>
allOf()
This matcher accepts a value when all its matchers accept the value. Greenlight checks the matchers in argument order and stops after a failure.
public static function allOf(
ArgumentMatcher $first,
ArgumentMatcher $second,
ArgumentMatcher ...$rest,
): ArgumentMatcherPHPDoc:
@template T@param ArgumentMatcher<T> $first@param ArgumentMatcher<T> $second@param ArgumentMatcher<T> ...$rest@return ArgumentMatcher<T>@throws InvalidDoubleUsage
captor()
This matcher accepts all values. It records the value when Greenlight selects the related expectation for the call.
public static function captor(): ArgumentCaptorArgumentCaptor
Namespace: Greenlight\Doubles
A captor records the argument in its position. It records the argument when Greenlight selects the related expectation for the call.
matches() always accepts the value and does not record it. Only the
expectation selected for the call can record an argument. Thus, checks of
candidate expectations cannot add values to a captor.
final class ArgumentCaptor implements ArgumentMatcherPHPDoc:
@template TValue = mixed
matches()
public function matches(mixed $value): booldescribe()
public function describe(): stringvalues()
public function values(): arrayPHPDoc:
@return list<TValue>
value()
public function value(): mixedPHPDoc:
@return TValue@throws InvalidDoubleUsage
ArgumentMatcher
Namespace: Greenlight\Doubles
An argument constraint for one position in with().
matches() determines if the matcher accepts a value in its position.
Candidate expectations can receive checks for calls that they do not
answer. Thus, matches() must not cause side effects. describe() identifies
the constraint in failure messages.
Use the Argument factories to get matchers.
interface ArgumentMatcherPHPDoc:
@template-covariant TValue = mixed
matches()
public function matches(mixed $value): bool;describe()
public function describe(): string;Doubles
Namespace: Greenlight\Doubles
Creates mocks, stubs, and spies. For intercepted methods, mocks fail on calls without a planned expectation. Each return value needs a configured result. Stubs cause an error for intercepted calls. Spies record intercepted calls to methods without a return value.
A verification failure throws one ExpectationFailed. It contains one
FailureDetail for each unmet expectation. Thus, the reporter shows it in
the same format as an Expect failure.
Doubles supports interfaces and classes that are neither final nor
readonly. Class constructors do not run. Final methods keep their original
implementation. Doubles does not support partial mocks or static interception.
Greenlight disposes injected factories after each test attempt. If you
construct a factory directly, call dispose() to verify its mocks.
final class Doubles implements Disposable__construct()
public function __construct(?string $proxyDirectory = null)PHPDoc:
@param string|null $proxyDirectory Directory for generated proxy classes. An empty string is invalid. The default is a project directory in the system temporary directory. A hash of the current working directory identifies it.@throws \InvalidArgumentException if the proxy directory is empty@throws InvalidDoubleUsage if PHP cannot resolve the default working directory
mock()
Creates a strict double. Disposal checks each planned expectation. An intercepted call without an expectation fails the test immediately.
public function mock(string $type, ?\Closure $plan = null): objectPHPDoc:
@template T of object@param class-string<T> $type@param \Closure(MockPlan<T>): void|null $plan@return T@throws InvalidDoubleUsage
stub()
Creates a double that satisfies the specified type. Intercepted calls cause a test error. Use a mock with explicit expectations when a collaborator must supply results.
public function stub(string $type): objectPHPDoc:
@template T of object@param class-string<T> $type@return T@throws InvalidDoubleUsage
spy()
Creates a spy that records intercepted calls and their arguments.
An intercepted method that returns a value causes a test error.
Use callsTo() to get the calls. Use Expect to check them.
public function spy(string $type): objectPHPDoc:
@template T of object@param class-string<T> $type@return T@throws InvalidDoubleUsage
callsTo()
Gets the calls to one method of a double from this factory. The result uses call order. Each entry contains the arguments for one call. The method must exist on the doubled type.
public function callsTo(object $double, string $method): arrayPHPDoc:
@return list<list<mixed>>@throws InvalidDoubleUsage
dispose()
Verifies mocks and clears their state when the test scope closes.
One ExpectationFailed contains the details for all unmet expectations.
public function dispose(): voidPHPDoc:
@throws ExpectationFailed
Fake
Namespace: Greenlight\Doubles
Identifies a manual in-memory test implementation.
The interface does not change behavior. It lets reporters and tools identify the object as an intentional fake, not production code under test.
interface FakeThis type does not declare public members.
InvalidDoubleUsage
Namespace: Greenlight\Doubles
Identifies incorrect use of the doubles API. Examples include an
unsupported type or a method that Doubles cannot intercept. Other examples
are a prohibited interaction or a return value without a configured
result.
These conditions are errors in the test code, not expectation failures. Thus, Greenlight reports the test as an error.
final class InvalidDoubleUsage extends \LogicExceptionstubWasCalled()
public static function stubWasCalled(string $type, string $method): selfreturnNotConfigured()
public static function returnNotConfigured(string $type, string $method): selfspyCannotAnswer()
public static function spyCannotAnswer(string $type, string $method): selfnoSuchMethod()
public static function noSuchMethod(string $type, string $method): selfnoSuchRecordedMethod()
public static function noSuchRecordedMethod(string $type, string $method): selfstaticMethod()
public static function staticMethod(string $type, string $method): selfneverMethodRequiresThrow()
public static function neverMethodRequiresThrow(string $type, string $method): selfmethodNotPublic()
public static function methodNotPublic(string $type, string $method): selffinalMethod()
public static function finalMethod(string $type, string $method): selfunsupportedReflectionType()
public static function unsupportedReflectionType(string $typeClass): selfparentTypeWithoutParent()
public static function parentTypeWithoutParent(string $context): selfunsupportedNestedReflectionType()
public static function unsupportedNestedReflectionType(string $typeClass): selfcannotDoubleEnum()
public static function cannotDoubleEnum(string $type): selfcannotDoubleReadonly()
public static function cannotDoubleReadonly(string $type): selfcannotDoubleFinal()
public static function cannotDoubleFinal(string $type): selfcannotDoubleTrait()
public static function cannotDoubleTrait(string $type): selfnotDoubleable()
public static function notDoubleable(string $type): selfattachHandlerCollision()
public static function attachHandlerCollision(string $class): selfhandlerPropertyCollision()
public static function handlerPropertyCollision(string $class): selfdefaultValueNotReproducible()
public static function defaultValueNotReproducible(string $parameter, string $class, string $method): selfdefaultConstantUnresolvable()
public static function defaultConstantUnresolvable(string $parameter): selfobjectDefaultNotReproducible()
public static function objectDefaultNotReproducible(string $parameter, string $class, string $method): selfobjectDefaultSourceUnavailable()
public static function objectDefaultSourceUnavailable(string $parameter, string $class, string $method): selfobjectDefaultScopeUnavailable()
public static function objectDefaultScopeUnavailable(string $parameter, string $class, string $method): selfproxyDirectoryNotCreated()
public static function proxyDirectoryNotCreated(string $directory, ?string $reason = null): selfproxyFileNotWritten()
public static function proxyFileNotWritten(string $file, \Throwable $cause): selfproxyFileNotLoaded()
public static function proxyFileNotLoaded(string $file, ?\Throwable $cause = null): selfworkingDirectoryUnresolved()
public static function workingDirectoryUnresolved(): selfforeignDouble()
public static function foreignDouble(string $class): selfinvalidTimes()
public static function invalidTimes(int $count): selfinvalidAtLeast()
public static function invalidAtLeast(int $count): selftooFewPlannedArguments()
public static function tooFewPlannedArguments(
string $selector,
string $type,
string $method,
int $actual,
int $required,
): selfPHPDoc:
@param class-string $type
tooManyPlannedArguments()
public static function tooManyPlannedArguments(
string $selector,
string $type,
string $method,
int $actual,
int $maximum,
): selfPHPDoc:
@param class-string $type
incompatiblePlannedArgumentMatcher()
public static function incompatiblePlannedArgumentMatcher(
string $selector,
string $type,
string $method,
int $position,
string $matcherType,
string $parameter,
string $parameterType,
): selfPHPDoc:
@param class-string $type
tooFewCallArguments()
public static function tooFewCallArguments(string $type, string $method, int $actual, int $required): selfPHPDoc:
@param class-string $type
tooManyCallArguments()
public static function tooManyCallArguments(string $type, string $method, int $actual, int $maximum): selfPHPDoc:
@param class-string $type
conflictingAnswers()
public static function conflictingAnswers(string $method): selfemptySequence()
public static function emptySequence(string $method): selfsequenceExhausted()
public static function sequenceExhausted(string $method, int $count): selfnothingCaptured()
public static function nothingCaptured(): selfinvalidCaptorPosition()
public static function invalidCaptorPosition(int $position): selfinvalidArgumentType()
public static function invalidArgumentType(): selfinvalidArgumentTypeCombination()
public static function invalidArgumentTypeCombination(string $factory): selfcompositeArgumentCaptor()
public static function compositeArgumentCaptor(): selfMethodExpectation
Namespace: Greenlight\Doubles
Defines one planned call pattern for a method of a double. The plan specifies the accepted arguments, cardinality, and result.
MockPlan::expects() creates this object. Its fluent plan methods are the
public interface. The call handler and verifier use members that have the
@internal tag.
Bare argument values use strict comparison (===). Use
Argument::equals() to apply deep equality.
final class MethodExpectationPHPDoc:
@template TTarget of object = object@template TMethod of non-empty-string = non-empty-string
$method
public readonly string $method;withNoArguments()
public function withNoArguments(): selfPHPDoc:
@throws InvalidDoubleUsage
with()
public function with(mixed $first, mixed ...$rest): selfPHPDoc:
@throws InvalidDoubleUsage
once()
public function once(): selftimes()
public function times(int $count): selfPHPDoc:
@throws InvalidDoubleUsage
atLeast()
public function atLeast(int $count): selfPHPDoc:
@throws InvalidDoubleUsage
never()
public function never(): selfandReturns()
public function andReturns(mixed $value): selfPHPDoc:
@throws InvalidDoubleUsage
andReturnsSequence()
Each accepted call consumes the next value. A call after the last value causes an error in the test code.
public function andReturnsSequence(mixed ...$values): selfPHPDoc:
@throws InvalidDoubleUsage
andReturnsUsing()
The closure receives the call arguments. The call returns the value from the closure.
public function andReturnsUsing(\Closure $answer): selfPHPDoc:
@throws InvalidDoubleUsage
andThrows()
public function andThrows(\Throwable $throwable): selfPHPDoc:
@throws InvalidDoubleUsage
captureArgument()
Records the argument at $position each time Greenlight selects this
expectation for a call. The method returns the captor and ends the
fluent chain. Before you call this method, configure the cardinality. If
the doubled method returns a value, configure its result first.
public function captureArgument(int $position = 0): ArgumentCaptorPHPDoc:
@return ArgumentCaptor<mixed>@throws InvalidDoubleUsage
MockPlan
Namespace: Greenlight\Doubles
Defines the mock plan that Doubles::mock() supplies to its closure.
Use the fluent methods to declare call patterns. The default cardinality is at least one call. The verifier checks each declared pattern when the test scope closes.
final readonly class MockPlanPHPDoc:
@template TTarget of object = object
any()
Returns the with() wildcard that accepts all values in its position.
public static function any(): ArgumentMatcherexpects()
public function expects(string $method): MethodExpectationPHPDoc:
@template TMethod of non-empty-string@param TMethod $method@return MethodExpectation<TTarget, TMethod>@throws InvalidDoubleUsage