.. index::
    single: Reference; Creating Test Doubles

Creating Test Doubles
=====================

Mockery's main goal is to help us create test doubles. It can create stubs,
mocks, and spies.

Stubs and mocks are created the same. The difference between the two is that a
stub only returns a preset result when called, while a mock needs to have
expectations set on the method calls it expects to receive.

Spies are a type of test doubles that keep track of the calls they received, and
allow us to inspect these calls after the fact.

When creating a test double object, we can pass in an identifier as a name for
our test double. If we pass it no identifier, the test double name will be
unknown. Furthermore, the identifier does not have to be a class name. It is a
good practice, and our recommendation, to always name the test doubles with the
same name as the underlying class we are creating test doubles for.

If the identifier we use for our test double is a name of an existing class,
the test double will inherit the type of the class (via inheritance), i.e. the
mock object will pass type hints or ``instanceof`` evaluations for the existing
class. This is useful when a test double must be of a specific type, to satisfy
the expectations our code has.

Stubs and mocks
---------------

Stubs and mocks are created by calling the ``\Mockery::mock()`` method. The
following example shows how to create a stub, or a mock, object named "foo":

.. code-block:: php

    $mock = \Mockery::mock('foo');

The mock object created like this is the loosest form of mocks possible, and is
an instance of ``\Mockery\MockInterface``.

.. note::

    All test doubles created with Mockery are an instance of
    ``\Mockery\MockInterface``, regardless are they a stub, mock or a spy.

To create a stub or a mock object with no name, we can call the ``mock()``
method with no parameters:

.. code-block:: php

    $mock = \Mockery::mock();

As we stated earlier, we don't recommend creating stub or mock objects without
a name.

Classes, abstracts, interfaces
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The recommended way to create a stub or a mock object is by using a name of
an existing class we want to create a test double of:

.. code-block:: php

    $mock = \Mockery::mock('MyClass');

This stub or mock object will have the type of ``MyClass``, through inheritance.

Stub or mock objects can be based on any concrete class, abstract class or even
an interface. The primary purpose is to ensure the mock object inherits a
specific type for type hinting.

.. code-block:: php

    $mock = \Mockery::mock('MyInterface');

This stub or mock object will implement the ``MyInterface`` interface.

.. note::

    Classes marked final, or classes that have methods marked final cannot be
    mocked fully. Mockery supports creating partial mocks for these cases.
    Partial mocks will be explained later in the documentation.

Mockery also supports creating stub or mock objects based on a single existing
class, which must implement one or more interfaces. We can do this by providing
a comma-separated list of the class and interfaces as the first argument to the
``\Mockery::mock()`` method:

.. code-block:: php

    $mock = \Mockery::mock('MyClass, MyInterface, OtherInterface');

This stub or mock object will now be of type ``MyClass`` and implement the
``MyInterface`` and ``OtherInterface`` interfaces.

.. note::

    The class name doesn't need to be the first member of the list but it's a
    friendly convention to use for readability.

We can tell a mock to implement the desired interfaces by passing the list of
interfaces as the second argument:

.. code-block:: php

    $mock = \Mockery::mock('MyClass', 'MyInterface, OtherInterface');

For all intents and purposes, this is the same as the previous example.

Spies
-----

The third type of test doubles Mockery supports are spies. The main difference
between spies and mock objects is that with spies we verify the calls made
against our test double after the calls were made. We would use a spy when we
don't necessarily care about all of the calls that are going to be made to an
object.

A spy will return ``null`` for all method calls it receives. It is not possible
to tell a spy what will be the return value of a method call. If we do that, then
we would deal with a mock object, and not with a spy.

We create a spy by calling the ``\Mockery::spy()`` method:

.. code-block:: php

    $spy = \Mockery::spy('MyClass');

Just as with stubs or mocks, we can tell Mockery to base a spy on any concrete 
or abstract class, or to implement any number of interfaces:

.. code-block:: php

    $spy = \Mockery::spy('MyClass, MyInterface, OtherInterface');

This spy will now be of type ``MyClass`` and implement the ``MyInterface`` and
``OtherInterface`` interfaces.

.. note::

    The ``\Mockery::spy()`` method call is actually a shorthand for calling
    ``\Mockery::mock()->shouldIgnoreMissing()``. The ``shouldIgnoreMissing``
    method is a "behaviour modifier". We'll discuss them a bit later.

Mocks vs. Spies
---------------

Let's try and illustrate the difference between mocks and spies with the
following example:

.. code-block:: php

    $mock = \Mockery::mock('MyClass');
    $spy = \Mockery::spy('MyClass');

    $mock->shouldReceive('foo')->andReturn(42);

    $mockResult = $mock->foo();
    $spyResult = $spy->foo();

    $spy->shouldHaveReceived()->foo();

    var_dump($mockResult); // int(42)
    var_dump($spyResult); // null

As we can see from this example, with a mock object we set the call expectations
before the call itself, and we get the return result we expect it to return.
With a spy object on the other hand, we verify the call has happened after the
fact. The return result of a method call against a spy is always ``null``.

We also have a dedicated chapter to :doc:`spies` only.

.. _creating-test-doubles-partial-test-doubles:

Partial Test Doubles
--------------------

Partial doubles are useful when we want to stub out, set expectations for, or
spy on *some* methods of a class, but run the actual code for other methods.

We differentiate between three types of partial test doubles:

 * runtime partial test doubles,
 * generated partial test doubles, and
 * proxied partial test doubles.

Runtime partial test doubles
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

What we call a runtime partial, involves creating a test double and then telling
it to make itself partial. Any method calls that the double hasn't been told to
allow or expect, will act as they would on a normal instance of the object.

.. code-block:: php

    class Foo {
        function foo() { return 123; }
        function bar() { return $this->foo(); }
    }

    $foo = mock(Foo::class)->makePartial();
    $foo->foo(); // int(123);

We can then tell the test double to allow or expect calls as with any other
Mockery double.

.. code-block:: php

    $foo->shouldReceive('foo')->andReturn(456);
    $foo->bar(); // int(456)

See the cookbook entry on :doc:`../cookbook/big_parent_class` for an example
usage of runtime partial test doubles.

Generated partial test doubles
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The second type of partial double we can create is what we call a generated
partial. With generated partials, we specifically tell Mockery which methods
we want to be able to allow or expect calls to. All other methods will run the
actual code *directly*, so stubs and expectations on these methods will not
work.

.. code-block:: php

    class Foo {
        function foo() { return 123; }
        function bar() { return $this->foo(); }
    }

    $foo = mock("Foo[foo]");

    $foo->foo(); // error, no expectation set

    $foo->shouldReceive('foo')->andReturn(456);
    $foo->foo(); // int(456)

    // setting an expectation for this has no effect
    $foo->shouldReceive('bar')->andReturn(999);
    $foo->bar(); // int(456)

It's also possible to specify explicitly which methods to run directly using
the `!method` syntax:

.. code-block:: php

    class Foo {
        function foo() { return 123; }
        function bar() { return $this->foo(); }
    }

    $foo = mock("Foo[!foo]");

    $foo->foo(); // int(123)

    $foo->bar(); // error, no expectation set

.. note::

    Even though we support generated partial test doubles, we do not recommend
    using them.

    One of the reasons why is because a generated partial will call the original
    constructor of the mocked class. This can have unwanted side-effects during
    testing application code.

    See :doc:`../cookbook/not_calling_the_constructor` for more details.

Proxied partial test doubles
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A proxied partial mock is a partial of last resort. We may encounter a class
which is simply not capable of being mocked because it has been marked as
final. Similarly, we may find a class with methods marked as final. In such a
scenario, we cannot simply extend the class and override methods to mock - we
need to get creative.

.. code-block:: php

    $mock = \Mockery::mock(new MyClass);

Yes, the new mock is a Proxy. It intercepts calls and reroutes them to the
proxied object (which we construct and pass in) for methods which are not
subject to any expectations. Indirectly, this allows us to mock methods
marked final since the Proxy is not subject to those limitations. The tradeoff
should be obvious - a proxied partial will fail any typehint checks for the
class being mocked since it cannot extend that class.

.. _creating-test-doubles-aliasing:

Aliasing
--------

Prefixing the valid name of a class (which is NOT currently loaded) with
"alias:" will generate an "alias mock". Alias mocks create a class alias with
the given classname to stdClass and are generally used to enable the mocking
of public static methods. Expectations set on the new mock object which refer
to static methods will be used by all static calls to this class.

.. code-block:: php

    $mock = \Mockery::mock('alias:MyClass');


.. note::

    Even though aliasing classes is supported, we do not recommend it.

Overloading
-----------

Prefixing the valid name of a class (which is NOT currently loaded) with
"overload:" will generate an alias mock (as with "alias:") except that created
new instances of that class will import any expectations set on the origin
mock (``$mock``). The origin mock is never verified since it's used an
expectation store for new instances. For this purpose we use the term "instance
mock" to differentiate it from the simpler "alias mock".

In other words, an instance mock will "intercept" when a new instance of the
mocked class is created, then the mock will be used instead. This is useful
especially when mocking hard dependencies which will be discussed later.

.. code-block:: php

    $mock = \Mockery::mock('overload:MyClass');

.. note::

    Using alias/instance mocks across more than one test will generate a fatal
    error since we can't have two classes of the same name. To avoid this,
    run each test of this kind in a separate PHP process (which is supported
    out of the box by both PHPUnit and PHPT).


.. _creating-test-doubles-named-mocks:

Named Mocks
-----------

The ``namedMock()`` method will generate a class called by the first argument,
so in this example ``MyClassName``. The rest of the arguments are treated in the
same way as the ``mock`` method:

.. code-block:: php

    $mock = \Mockery::namedMock('MyClassName', 'DateTime');

This example would create a class called ``MyClassName`` that extends
``DateTime``.

Named mocks are quite an edge case, but they can be useful when code depends
on the ``__CLASS__`` magic constant, or when we need two derivatives of an
abstract type, that are actually different classes.

See the cookbook entry on :doc:`../cookbook/class_constants` for an example
usage of named mocks.

.. note::

    We can only create a named mock once, any subsequent calls to
    ``namedMock``, with different arguments are likely to cause exceptions.

.. _creating-test-doubles-constructor-arguments:

Constructor Arguments
---------------------

Sometimes the mocked class has required constructor arguments. We can pass these
to Mockery as an indexed array, as the 2nd argument:

.. code-block:: php

    $mock = \Mockery::mock('MyClass', [$constructorArg1, $constructorArg2]);

or if we need the ``MyClass`` to implement an interface as well, as the 3rd
argument:

.. code-block:: php

    $mock = \Mockery::mock('MyClass', 'MyInterface', [$constructorArg1, $constructorArg2]);

Mockery now knows to pass in ``$constructorArg1`` and ``$constructorArg2`` as
arguments to the constructor.

.. _creating-test-doubles-behavior-modifiers:

Behavior Modifiers
------------------

When creating a mock object, we may wish to use some commonly preferred
behaviours that are not the default in Mockery.

The use of the ``shouldIgnoreMissing()`` behaviour modifier will label this
mock object as a Passive Mock:

.. code-block:: php

    \Mockery::mock('MyClass')->shouldIgnoreMissing();

In such a mock object, calls to methods which are not covered by expectations
will return ``null`` instead of the usual error about there being no expectation
matching the call.

On PHP >= 7.0.0, methods with missing expectations that have a return type
will return either a mock of the object (if return type is a class) or a
"falsy" primitive value, e.g. empty string, empty array, zero for ints and
floats, false for bools, or empty closures.

On PHP >= 7.1.0, methods with missing expectations and nullable return type
will return null.

We can optionally prefer to return an object of type ``\Mockery\Undefined``
(i.e.  a ``null`` object) (which was the 0.7.2 behaviour) by using an
additional modifier:

.. code-block:: php

    \Mockery::mock('MyClass')->shouldIgnoreMissing()->asUndefined();

The returned object is nothing more than a placeholder so if, by some act of
fate, it's erroneously used somewhere it shouldn't, it will likely not pass a
logic check.

We have encountered the ``makePartial()`` method before, as it is the method we
use to create runtime partial test doubles:

.. code-block:: php

    \Mockery::mock('MyClass')->makePartial();

This form of mock object will defer all methods not subject to an expectation to
the parent class of the mock, i.e. ``MyClass``. Whereas the previous
``shouldIgnoreMissing()`` returned ``null``, this behaviour simply calls the
parent's matching method.