Mocking

PhpSpec includes a built-in mocking system, no external libraries required. It generates test doubles at runtime using reflection and eval().

Creating Doubles

Using mock()

Use the global mock() function:

$double = mock(UserRepository::class);

This generates a dynamic subclass (or implementation, for interfaces) that:

  • Extends the original class (or implements the interface)
  • Overrides all methods to track calls
  • Is made without running the class's constructor

Some built-in interfaces PHP lets no plain class implement, so a double of an interface built on one is built the way PHP allows:

Built onThe double
Traversableis an IteratorAggregateits getIterator() iterates nothing unless stubbed: allow($bag->getIterator())->toReturn(new ArrayIterator([...]))
Throwableextends Exceptionit can be thrown; getMessage() and the other methods Exception declares final answer as an Exception does, and cannot be stubbed
DateTimeInterfaceextends DateTimeImmutableits methods are stubbed as any other
UnitEnumcannot be madeonly an enum can implement it, so mock() and dummy() refuse it, saying so; a method returning it answers a case of an enum implementing it (see below)

An extension may refuse a plain class too: PhpSpec asks PHP once per run, and a double PHP refuses is refused with PHP's reason:

Cannot create a test double for interface App\Labelled. Only an enum can implement UnitEnum.

A double of several interfaces, such as what a method returning Wide&Narrow answers, takes every call each of them declares, and returns what every declared return type admits. A method returning Traversable in one and ArrayIterator in the other returns ArrayIterator, and one returning Countable and Traversable returns Countable&Traversable. The same holds between an interface and the base a double of it is built on. Where no value can satisfy every return type, such as int and string, or two classes neither extends, the method is refused when called:

App\Sized::size() returns int and App\Named::size() returns string, so no value can be returned for both.

A class named with interfaces, such as what a method returning Base&HasValue answers, keeps what it is: its final methods, and an Error or a DateTime it already extends where an interface needs a Throwable or a DateTimeInterface, the serialization methods it has, and the iterator it already is. A subclass of it adds what it can for a Traversable interface: an IteratorAggregate where its getIterator() allows one, so stubbing getIterator() rules foreach, else an Iterator. A double iterating as an Iterator is refused where its valid() is final, or resolves to a type without false, since no double of it could end the iteration. What a dummy aggregate's getIterator() answers iterates as empty: an aggregate whose own getIterator() leads to an Iterator without coming back to an aggregate on the way, else an empty Iterator, trying each type of a union in turn. Where none can be, iterating the dummy is refused, saying what keeps it from one, and a mock() can still stub the call. A class declaring static, and not private, a method an interface declares on an object cannot be that interface. A class is the class it names however it is spelled, through an alias or in another case, and an intersection one of its types already satisfies is answered as that type.

A double inherits a static method the class implements. One it must implement, abstract in an interface or a class, is refused when called, since a double answers on an object, not on its class:

App\FromData::fromData() is static, so no double can answer it.

A method a type declares only by an @method tag, on itself, a parent class or an interface, as libraries do for a method they keep for a later major version, is a method of its double too: stubbed, expected and spied on like any other. It takes any arguments and returns any value, since the tag's types are the docblock's rather than PHP's. A tag reading @method static Foo make() declares a static one, refused when called like the one above; @method static make() is a method on the object that returns static.

Declarations no class can implement together, a parameter one takes by reference and another by value, a method one declares static and another on an object, or a method narrowing one the base declares final, are refused: by mock() and dummy() at once, and as a return type only when the method returning it is called:

Cannot create a test double for interface App\Failure. App\Failure::getPrevious() narrows a method Exception declares final.

A double of a class never runs the class's constructor, which would run the application's initialization with arguments nobody gave. Its properties keep the defaults they declare; a promoted property, or any other the constructor sets, stays uninitialised, so a final method that reads one needs a real instance instead. A double of an interface built on DateTimeImmutable or Exception is initialised as that base is.

Using dummy()

A double from mock() is strict: a call to it that the spec never declared, made from the code under spec, fails the example unless a toHaveBeenCalled() after the act checks it. dummy() makes a double that stands in for the real thing with no behaviour, for a collaborator whose calls do not matter, a logger passed along for instance:

$logger = dummy(Logger::class);

Every call returns a default for its return type, and a method returning a class or interface answers a dummy of it, so a chain the code under spec follows is answered with defaults at any depth. A dummy takes no stub or expectation, and neither does what it answered. A spec that needs one needs a mock(), which ends a stub in ignoreOthers() when only some calls matter:

App\Book::pages() was stubbed on a dummy. Use mock() instead of dummy().
App\Page::title() was stubbed on what dummy App\Book::first()->next() answered. Use mock() instead of dummy() and stub App\Book::first().

Type-Hinted Mock Injection

Both it() and this() closures support type-hinted parameters that are automatically resolved as mocks:

describe(UserService::class, function () {
    // Injected via this()
    this('service', fn (UserRepository $repo) => new UserService($repo));

    // Injected via it()
    it('finds a user', function (UserRepository $repo) {
        allow($repo->find(1))->toReturn(['name' => 'Alice']);
        $service = new UserService($repo);
        expect($service->getDisplayName(1))->toBe('Alice');
    });
});

Any parameter with a class or interface type hint will be automatically resolved via mock(). This is the preferred way to create mocks. A parameter is always a double, the same for every closure of the example that names it alike; Hooks has which of them sit on $this.

Stubbing Return Values

allow() + toReturn()

The allow() function stubs a method to return a specific value:

it('returns user data', function (UserRepository $repo) {
    allow($repo->find(1))->toReturn(['name' => 'Alice']);

    $result = $repo->find(1);
    expect($result)->toBe(['name' => 'Alice']);
});

andReturn() is another name for toReturn().

The value has to be one the real method could return, held strictly: a method returning int is not given '42', and one returning void is not given anything, its call is declared with allow() alone. A value it could never return is refused where the spec sets it:

App\Counter::count() returns int, so it cannot return string "three".

What a toReturnUsing() callback answers is held the same way when the call is made.

A callback is handed the call's arguments as PHP hands them to the real method. One the method takes by reference reaches the callback as that reference, so what the callback writes into it reaches the caller. A method that returns by reference hands back the reference a callback returns by reference. A value given to toReturn() is always handed back as a copy:

allow($cache->get('key', $anything))->toReturnUsing(function (string $key, ?array &$metadata): string {
    $metadata = ['hit' => true];

    return 'value';
});

allow() + toThrow()

Stub a method to throw an exception:

it('handles errors', function (UserRepository $repo) {
    allow($repo->find(999))->toThrow(new \RuntimeException('Not found'));

    expect(fn () => $repo->find(999))->toThrow(\RuntimeException::class);
});

Give it the very instance to throw, as above, or a class name and a message and it builds one at the call: toThrow(\RuntimeException::class, 'Not found').

Stubs answer in the order they were declared

Each call the code under spec makes is answered by the first stub that matches it and has not answered yet; once every matching stub has answered, the last one answers on. Two stubs of the same call answer one call after the other:

allow($repo->find(1))->toThrow(new \RuntimeException('Busy'));
allow($repo->find(1))->toReturn('Alice'); // the second find(1), and every one after

Stubs that overlap are used in order too: a find(42) declared after a find(any()) answers only once find(any()) has. A stub every example needs belongs in beforeEach; one an example would replace belongs in that example.

The spec's own calls use no stub up and have its exception withheld, so the second allow($repo->find(1)) above declares the call rather than throwing. They see the value the next stub would give, and toThrow() sees the exception it would throw: expect(fn () => $repo->find(1))->toThrow(...).

What an unstubbed call returns

A method nobody stubbed returns a default for its return type: '', 0, false, [], null where allowed, an answer of the class or interface it returns (of the first a union of them names, a built-in interface such as DateTimeInterface or Countable included), an empty iterable, a Closure, an empty Generator, true or false for those types, the double itself for static, self and parent. A nullable class or interface of your own answers a double of it, a nullable built-in interface null. A union of your own classes and interfaces that allows null answers as it would without null (Page|Book|null a Page double, Book|Page|null a Book one), and null when none of them can have a double; one that also holds a scalar or a built-in type answers null. A stub can still return null. A method returning an interface only an enum can implement answers, as one returning that enum would, the first case of the first enum by name that implements it, directly or through an interface extending it. That enum is one already loaded, or one the project's source declares: in the directories Composer and the autoload configuration load the project's classes from, and under the interface's own namespace. The source is read for its declarations, and only an enum that could be one is loaded, to check it. With no such enum the method is refused when it is called, with the reason. A method returning a final class hands the spec an instance of it built without its constructor, for allow() to replace. A lenient double has nobody about to replace it, so it refuses the code under spec, still handing the spec's own call the instance allow() needs. A type no double nor instance can stand in for, such as an internal final class, is refused, saying why.

An answer stands for the call that returned it, for allow() and expect() to take. A lenient double, a dummy() or one that ignores others, answers a dummy. A strict double's answer is not for use: a call on it is refused, naming the call to stub, and the code under spec catching the refusal still fails the example. A chain the code under spec follows is stubbed one call at a time, each with a double of its own:

allow($book->first())->toReturn($page);
allow($page->next())->toReturn($second);
App\Page::next() was called on what App\Book::first() answered, at src/App/Reader.php:8. Stub App\Book::first().

A spec that wants defaults from the answer returns a dummy, and the double stays strict: allow($book->first())->toReturn(dummy(App\Page::class)).

Calls the spec never declared

A double is strict towards the code under spec. A call that no allow() or expect() declared and no toHaveBeenCalled() checks, made from anywhere outside the spec code, fails the example. The spec code is every file PhpSpec loaded as a spec, step or support file, wherever it sits, and whatever sits in the spec, features and suite folders, or the folder of a path the run was given:

App\Stock::reserve("tea", 2) was called but not expected, at src/App/Checkout.php:8.

A call is declared by the arguments it was written with, read as PHP reads the call: any() stands for one argument whose value does not matter, cetera() for the rest, and a call that leaves out an argument with a default is the call with that default. allow() declares on its own, a stub is optional:

allow($stock->reserve('tea', 2));                 // reserve('tea', 2) may be called, returns false
allow($stock->reserve('tea', 2))->toReturn(true); // and returns true
expect($stock->reserve(cetera()))->toBeCalled();  // any reserve() may be called, and must be

reserve() is a call with no arguments, which no object taking two could be given, so it is refused where the spec writes it:

App\Stock::reserve() takes 2 arguments (string $item, int $quantity), so a call written with none can never be made.
Write the arguments it is called with, any() for one whose value does not matter, or cetera() for the rest.

An argument of a type the method does not take is refused the same way. The code under spec calling a double with too few arguments, or with an argument of the wrong type, fails as it would on the real object, its argument coerced or held strictly as the file it calls from declares:

App\Stock::reserve(): Argument #2 ($quantity) must be of type int, string given, called in src/App/Checkout.php on line 11

The spec file itself is free to call anything: that is how allow() and expect() reach the call they declare. A collaborator whose calls do not matter is a dummy(). A stub that stubs only what matters, and answers the rest with defaults, ends a stub in ignoreOthers():

beforeEach(function (Filesystem $fs) {
    allow($fs->exists(any()))->toReturn(false);
    allow($fs->isDir(any()))->toReturn(false)->ignoreOthers();
});

How a failure names a double

A failure names a double by the type it stands for and a number, with the parameter names it was handed under:

Expected App\Context double #2 ($second) to be App\Context double #1 ($first)

An example numbers its doubles in the order it makes them: a parameter's when the first closure naming it runs, and one from mock() or dummy() where it is called. What a double answered is named by the type its call declares (mixed for none) and by where it came from, and numbered when a failure first shows it:

App\Page double #3 (from App\Book double #1->first())

A double keeps its number for the whole example, and every format shows the same one, whichever worker ran the example. Each example and each scenario numbers from one.

Verifying Method Calls

Stub and verify the same call in any order: a stubbed call still records that it was made, and its returned value still compares with the ordinary matchers.

toBeCalled()

Declared before the act, judged when the example ends: the method must be called at least once by then. Arguments written in the expect call are part of the promise: save($user) is not satisfied by a save() of something else, save(any()) by a save() of anything. The declaration also makes the call expected, so the code under spec may make it:

it('calls save', function (UserRepository $repo) {
    expect($repo->save($user))->toBeCalled();

    (new Registration($repo))->register($user);
});

it('saves something', function (UserRepository $repo) {
    expect($repo->save(any()))->toBeCalled();

    (new Registration($repo))->register($anyUser);
});

toHaveBeenCalled()

Asked after the act, judged at once from the calls made so far. Nothing needs declaring before the act.

it('saves the user', function (UserRepository $repo) {
    (new Registration($repo))->register($user);

    expect($repo->save($user))->toHaveBeenCalled();
});

Negated, it asks that the call was not made: expect($repo->save($other))->not()->toHaveBeenCalled().

A count follows it, judged from the same calls: ->once(), ->twice(), ->exactly(3)->times(), ->atLeast(2)->times() or ->atMost(2)->times().

expect($mailer->send(any()))->toHaveBeenCalled()->twice();

Counting calls

toBeCalled() takes how many times, counting the calls that match the arguments the call was written with; a call that must not happen is not()->toBeCalled():

expect($logger->log('test'))->toBeCalled()->once();
expect($logger->log('test'))->toBeCalled()->twice();
expect($logger->log('test'))->toBeCalled()->exactly(3)->times();
expect($logger->log('test'))->toBeCalled()->atLeast(2)->times();
expect($logger->log('test'))->toBeCalled()->atMost(2)->times();
expect($logger->log('other'))->not()->toBeCalled();

Argument Matchers

An argument written as a value matches by value: a scalar strictly, an object when it equals the one written (new Money(900) matches any Money(900), whichever instance carries it), an array element by element on the same rule. A double matches only itself, never another double of the same type. What a double answered matches what the same double answers to the same method, whatever the arguments, so a spy names it by that call again:

(new Reader($book, $printer))->read(); // prints what $book->first() answers
expect($printer->print($book->first()))->toHaveBeenCalled();

For anything looser, write a matcher in the call:

any()

Matches any single argument:

expect($logger->log(any()))->toBeCalled();

type(string $type)

Matches an argument of a specific type:

expect($repo->save(type('object')))->toBeCalled();

callback(Closure $fn)

Matches using a custom callback:

expect($repo->save(callback(fn ($arg) => $arg->name === 'Alice')))->toBeCalled();

satisfy(Closure $fn)

Matches a single argument against a predicate, as callback() does, and reads well alongside the others:

expect($repo->save(satisfy(fn ($u) => $u->isActive())))->toBeCalled();

anInstanceOf(string $class)

Matches an argument that is an instance of the given class or interface:

expect($bus->dispatch(anInstanceOf(Command::class)))->toBeCalled();

arrayIncluding(array $subset)

Matches an array argument that contains (at least) the given key/value subset:

expect($api->send(arrayIncluding(['type' => 'order'])))->toBeCalled();

startWith(string $prefix)

Matches a string argument that starts with the given prefix:

expect($logger->log(startWith('ERROR:')))->toBeCalled();

cetera()

Matches the remaining arguments, none or more: the "and so on" wildcard. Nothing can follow it:

expect($logger->log('hello', cetera()))->toBeCalled();

Negation

All mock matchers support negation via not():

expect($repo->delete(1))->not()->toBeCalled();
expect($logger->log('other'))->not()->toBeCalled();

Using Mocks with this()

describe(Notifier::class, function () {
    this('mailer', fn () => mock(Mailer::class));
    this('notifier', fn () => new Notifier($this->mailer));

    it('sends an email', function () {
        expect($this->mailer->send('hello'))->toBeCalled();
        $this->notifier->notify('hello');
    });
});

Or using type-hinted injection in this():

describe(Notifier::class, function () {
    this('notifier', fn (Mailer $mailer) => new Notifier($mailer));

    it('sends an email', function () {
        // $this->mailer is available from this() injection
    });
});

Coming from Prophecy

A call is written as in Prophecy, as the call itself, and read the same way: $repo->find() is a call with no arguments, never find(1). Where the method requires an argument, that call is refused where the spec writes it, so a not()->toBeCalled() can never pass for a call that could not happen.

ProphecyPhpSpec 9
$repo->find(1)->willReturn('Alice')allow($repo->find(1))->toReturn('Alice')
$repo->find(1)->willThrow(NotFound::class)allow($repo->find(1))->toThrow(NotFound::class)
$repo->find(1)->will(fn ($args) => ...)allow($repo->find(1))->toReturnUsing(fn ($id) => ...)
$repo->save($user)->shouldBeCalled()expect($repo->save($user))->toBeCalled()
$repo->save($user)->shouldBeCalledTimes(2)expect($repo->save($user))->toBeCalled()->exactly(2)->times()
$repo->save(Argument::cetera())->shouldNotBeCalled()expect($repo->save(cetera()))->not()->toBeCalled()
$repo->save($user)->shouldHaveBeenCalled()expect($repo->save($user))->toHaveBeenCalled()
$repo->save($user)->shouldHaveBeenCalledTimes(2)expect($repo->save($user))->toHaveBeenCalled()->twice()
Argument::any(), Argument::cetera()any(), cetera()
Argument::type('string')type('string')
Argument::that(fn ($user) => ...)satisfy(fn ($user) => ...)

Supported Types

The mock system handles:

  • Classes: generates a subclass
  • Interfaces: generates an implementation
  • Nullable types (?Foo): wraps return with null handling
  • Union types (Foo|Bar): answers with the first type that can have an answer
  • Intersection types (Foo&Bar): creates a combined implementation
  • Enum types: returns the first case as default
  • Scalar return types (string, int, float, bool, array): returns type-appropriate defaults

Limitations

  • Final classes cannot be mocked (PHP reflection limitation)
  • Readonly classes cannot be mocked