Yu1709$!%yuyu!$%wutu!5=126+

                
____  ___       .__                 
\   \/  /  _____|  |   ______  _  __
 \     /  /  ___/  |  /  _ \ \/ \/ /
 /     \  \___ \|  |_(  <_> )     / 
/___/\  \/____  >____/\____/ \/\_/  
      \_/     \/    @ligmakokz

Editing: expectations.rst

.. index::
    single: Expectations

Expectation Declarations
========================

Once you have created a mock object, you'll often want to start defining how
exactly it should behave (and how it should be called). This is where the
Mockery expectation declarations take over.

.. code-block:: php

shouldReceive(method_name)

Declares that the mock expects a call to the given method name. This is the
starting expectation upon which all other expectations and constraints are
appended.

.. code-block:: php

shouldReceive(method1, method2, ...)

Declares a number of expected method calls, all of which will adopt any
chained expectations or constraints.

.. code-block:: php

shouldReceive(array('method1'=>1, 'method2'=>2, ...))

Declares a number of expected calls but also their return values. All will
adopt any additional chained expectations or constraints.

.. code-block:: php

shouldReceive(closure)

Creates a mock object (only from a partial mock) which is used to create a
mock object recorder. The recorder is a simple proxy to the original object
passed in for mocking. This is passed to the closure, which may run it through
a set of operations which are recorded as expectations on the partial mock. A
simple use case is automatically recording expectations based on an existing
usage (e.g. during refactoring). See examples in a later section.

.. code-block:: php

shouldNotReceive(method_name)

Declares that the mock should not expect a call to the given method name. This
method is a convenience method for calling ``shouldReceive()->never()``.

.. code-block:: php

with(arg1, arg2, ...) / withArgs(array(arg1, arg2, ...))

Adds a constraint that this expectation only applies to method calls which
match the expected argument list. You can add a lot more flexibility to
argument matching using the built in matcher classes (see later). For example,
``\Mockery::any()`` matches any argument passed to that position in the
``with()`` parameter list. Mockery also allows Hamcrest library matchers - for
example, the Hamcrest function ``anything()`` is equivalent to
``\Mockery::any()``.

It's important to note that this means all expectations attached only apply to
the given method when it is called with these exact arguments. This allows for
setting up differing expectations based on the arguments provided to expected
calls.

.. code-block:: php

withAnyArgs()

Declares that this expectation matches a method call regardless of what
arguments are passed. This is set by default unless otherwise specified.

.. code-block:: php

withNoArgs()

Declares this expectation matches method calls with zero arguments.

.. code-block:: php

andReturn(value)

Sets a value to be returned from the expected method call.

.. code-block:: php

andReturn(value1, value2, ...)

Sets up a sequence of return values or closures. For example, the first call
will return value1 and the second value2. Note that all subsequent calls to a
mocked method will always return the final value (or the only value) given to
this declaration.

.. code-block:: php

andReturnNull() / andReturn([NULL])

Both of the above options are primarily for communication to test readers.
They mark the mock object method call as returning ``null`` or nothing.

.. code-block:: php

andReturnValues(array)

Alternative syntax for ``andReturn()`` that accepts a simple array instead of
a list of parameters. The order of return is determined by the numerical
index of the given array with the last array member being return on all calls
once previous return values are exhausted.

.. code-block:: php

andReturnUsing(closure, ...)

Sets a closure (anonymous function) to be called with the arguments passed to
the method. The return value from the closure is then returned. Useful for
some dynamic processing of arguments into related concrete results. Closures
can queued by passing them as extra parameters as for ``andReturn()``.

.. note::

You cannot currently mix ``andReturnUsing()`` with ``andReturn()``.

.. code-block:: php

andThrow(Exception)

Declares that this method will throw the given ``Exception`` object when
called.

.. code-block:: php

andThrow(exception_name, message)

Rather than an object, you can pass in the ``Exception`` class and message to
use when throwing an ``Exception`` from the mocked method.

.. code-block:: php

andSet(name, value1) / set(name, value1)

Used with an expectation so that when a matching method is called, one can
also cause a mock object's public property to be set to a specified value.

.. code-block:: php

passthru()

Tells the expectation to bypass a return queue and instead call the real
method of the class that was mocked and return the result. Basically, it
allows expectation matching and call count validation to be applied against
real methods while still calling the real class method with the expected
arguments.

.. code-block:: php

zeroOrMoreTimes()

Declares that the expected method may be called zero or more times. This is
the default for all methods unless otherwise set.

.. code-block:: php

once()

Declares that the expected method may only be called once. Like all other call
count constraints, it will throw a ``\Mockery\CountValidator\Exception`` if
breached and can be modified by the ``atLeast()`` and ``atMost()``
constraints.

.. code-block:: php

twice()

Declares that the expected method may only be called twice.

.. code-block:: php

times(n)

Declares that the expected method may only be called n times.

.. code-block:: php

never()

Declares that the expected method may never be called. Ever!

.. code-block:: php

atLeast()

Adds a minimum modifier to the next call count expectation. Thus
``atLeast()->times(3)`` means the call must be called at least three times
(given matching method args) but never less than three times.

.. code-block:: php

atMost()

Adds a maximum modifier to the next call count expectation. Thus
``atMost()->times(3)`` means the call must be called no more than three times.
This also means no calls are acceptable.

.. code-block:: php

between(min, max)

Sets an expected range of call counts. This is actually identical to using
``atLeast()->times(min)->atMost()->times(max)`` but is provided as a
shorthand.  It may be followed by a ``times()`` call with no parameter to
preserve the APIs natural language readability.

.. code-block:: php

ordered()

Declares that this method is expected to be called in a specific order in
relation to similarly marked methods. The order is dictated by the order in
which this modifier is actually used when setting up mocks.

.. code-block:: php

ordered(group)

Declares the method as belonging to an order group (which can be named or
numbered). Methods within a group can be called in any order, but the ordered
calls from outside the group are ordered in relation to the group, i.e. you
can set up so that method1 is called before group1 which is in turn called
before method 2.

.. code-block:: php

globally()

When called prior to ``ordered()`` or ``ordered(group)``, it declares this
ordering to apply across all mock objects (not just the current mock). This
allows for dictating order expectations across multiple mocks.

.. code-block:: php

byDefault()

Marks an expectation as a default. Default expectations are applied unless a
non-default expectation is created. These later expectations immediately
replace the previously defined default. This is useful so you can setup
default mocks in your unit test ``setup()`` and later tweak them in specific
tests as needed.

.. code-block:: php

getMock()

Returns the current mock object from an expectation chain. Useful where you
prefer to keep mock setups as a single statement, e.g.

.. code-block:: php

$mock = \Mockery::mock('foo')->shouldReceive('foo')->andReturn(1)->getMock();

Name	Type	Actions
mockery	Directory
argument_validation.rst	File
demeter_chains.rst	File
expectations.rst	File
final_methods_classes.rst	File
index.rst	File
instance_mocking.rst	File
magic_methods.rst	File
map.rst.inc	File
object_recording.rst	File
partial_mocks.rst	File
pass_by_reference_behaviours.rst	File
phpunit_integration.rst	File
public_properties.rst	File
public_static_properties.rst	File
quick_examples.rst	File
startup_methods.rst	File