===
API
===

Double classes
==============

.. py:class:: Stub([collaborator])
.. py:class:: Spy([collaborator])
.. py:class:: ProxySpy([collaborator])
.. py:class:: Mock([collaborator])

.. py:class:: Mimic(double, collaborator)


Stubbing
========

.. py:method:: Method.raises(exception)

   Stub method will raise the given `exception` when invoked. Method parameters are
   relevant, and they may be literal values or hamcrest matchers::

       with Stub() as stub:
           stub.method().raises(ValueError)

   See :ref:`raises`.

.. py:method:: Method.returns(value)

   Stub method will return the given value when invoked::

       with Stub() as stub:
           stub.method().returns(100)

   See :ref:`stub`.

.. py:method:: Method.returns_input()

   Stub method will return input parameters when invoked::

       with Stub() as stub:
           stub.method().returns_input()

   See :ref:`returns_input`.


.. py:method:: Method.delegates(delegate)

   Stub method will return values generated by the `delegate`, that may be a function,
   generator or iterable object::

       with Stub() as stub:
           stub.method().delegates([1, 2, 4, 8])

   See :ref:`delegates`.


.. py:method:: Method.attach(callable)

   Stub methods are observable. You may attach arbitrary callable that will be invoked any
   time the stub method does::

       counter = itertools.count()
       stub.method.attach(counter.next)

   See :ref:`observers`.


Matchers
========

.. py:class:: never(matcher)

   Just a cosmetic alias to the hamcrest matcher :py:func:`is_not`. See :ref:`never`.


for Spy methods
---------------

.. py:class:: called

   Asserts a spy method was called::

       assert_that(spy.method, called())

   See :ref:`called`.

.. py:method:: called.async_mode(timeout)

   The ``called`` assertion waits the corresponding invocation a maximum of `timeout`
   seconds.

   :param int timeout: how many second wait before assume assertion fails.

   ::

       assert_that(spy.method, called().async_mode(1))

   See :ref:`async_mode`.


.. py:method:: called.times(value)

   The spy method must be invoked `value` times to consider the assertion right. The
   `value` parameter may an integer or hamcrest matcher as well.

   :param value: how many times the method should be called.
   :type value: int or hamcrest Matcher

   ::

       assert_that(spy.method, called().times(less_that(3)))

   See :ref:`times`.

.. py:method:: called.with_args(*args, **kargs)

   The spy method must be invoked with the given positional or/and named parameters. All
   of them may be literal values and hamcrest matchers.

   ::

       assert_that(spy.method, called().with_args("mary", greater_that(4)))

   See :ref:`with_args`.


.. py:method:: called.with_some_args(**kargs)

   The spy method must be invoked with AT LEAST the given parameter values. It supports
   literal values and hamcrest matchers.

   ::

       assert_that(spy.method, called().with_some_args(name="mary"))

   See :ref:`with_some_args`.


for properties
--------------

.. py:class:: property_got()
.. py:class:: property_set()
.. py:method:: property_set.to(value)

See :ref:`properties`.


for mocks
---------

.. py:class:: verify()

   Checks the given mock meets the given expectations.

   ::

       assert_that(mock, verify())

   See :ref:`verify`.

.. py:class:: any_order_verify()

   Checks the given mock meets the given expectations even when the invocation sequence
   has a different order to the expectations.

   ::

       assert_that(mock, any_order_verify())

   See :ref:`verify`.


Module level functions
======================

.. py:function:: assert_that(item, matcher)

   A convenient replace for the hamcrest `assert_that` method. See :ref:`sec assert_that`.


.. py:function:: wait_that(item, matcher, reason='', delta=1, timeout=5)

   It test the `matcher` over `item` until it matches or fails after `timemout` seconds,
   polling the matcher each `delta` seconds.


.. py:function:: method_returning(value)

   Creates an independent Stub method that returns the given value. It may be added to any
   object::

       some.method = method_returning(20)

   See :ref:`ad-hoc methods`.


.. py:function:: method_raising()

   Creates an independent Stub method that raises the given exception. It may be added to
   any object::

       some.method = method_raising(ValueError)

   See :ref:`ad-hoc methods`.


.. py:function:: set_default_behavior()

   Set the default behavior for undefined Stub methods. The built-in behavior is to return
   **None**. See :ref:`set_default_behavior`.


.. Local Variables:
..  coding: utf-8
..  mode: rst
..  mode: flyspell
..  ispell-local-dictionary: "american"
..  fill-column: 90
.. End:
