====================================
 Mock - Mocking and Testing Library
====================================

:Author: `Michael Foord <http://www.voidspace.org.uk/python/weblog/index.shtml>`_
:Co-maintainer: `Konrad Delong <http://konryd.blogspot.com/>`_
:Version: Mock 0.7.0 beta 1
:Date: 2010/06/XX
:Homepage: `Mock Homepage`_
:Download: `Mock on PyPI`_
:Documentation: `PDF Documentation <http://www.voidspace.org.uk/downloads/mock.pdf>`_
:License: `BSD License`_
:Support: `Testing in Python Email List <http://lists.idyll.org/listinfo/testing-in-python>`_
:Issue tracker: `Google code project <http://code.google.com/p/mock/issues/list>`_

.. _Mock Homepage: http://www.voidspace.org.uk/python/mock/
.. _BSD License: http://www.voidspace.org.uk/python/license.shtml


.. currentmodule:: mock

.. module:: mock
   :synopsis: Mock object and testing library.

mock provides a core :class:`Mock` class that is intended to reduce
the need to create a host of trivial stubs throughout your test suite. After
performing an action, you can make assertions about which methods / attributes
were used and arguments they were called with. You can also specify return
values and set specific attributes in the normal way.

The mock module also provides a :func:`patch` decorator that handles
patching module and class level attributes within the scope of a test, along
with :const:`sentinel` for creating unique objects. See the `quick guide`_ for
some examples of how to use ``Mock``, ``MagicMock`` and ``patch``.

Mock is very easy to use and is designed for use with
`unittest <http://pypi.python.org/pypi/unittest2 unittest>`_. Mock is based on
the 'action -> assertion' pattern instead of 'record -> replay' used by many
mocking frameworks.

mock is tested on Python versions 2.4-2.7 and Python 3.


.. testsetup::
   
   import sys
   class ProductionClass(object):
      def method(self, *args):
         pass
   
   test_module = sys.modules['test_module'] = ProductionClass
   ProductionClass.ClassName1 = ProductionClass
   ProductionClass.ClassName2 = ProductionClass


API Documentation
=================

.. toctree::
   :maxdepth: 2
   
   mock
   patch
   sentinel
   magicmock
   mocksignature


User Guide
==========

.. toctree::
   :maxdepth: 2

   getting-started
   examples
   changelog


Installing
==========

The current version is **0.7.0 beta 1**, dated XXXX. Mock is still 
experimental; the API may change. If you find bugs or 
have suggestions for improvements / extensions then please email me.

* `mock on PyPI <http://pypi.python.org/pypi/mock>`_
* `mock documentation as PDF <http://www.voidspace.org.uk/downloads/mock.pdf>`_
* `Google Code Home & Subversion Repository <http://code.google.com/p/mock/>`_

You can checkout the latest development version from the Google Code Subversion 
repository with the following command:

    ``svn checkout http://mock.googlecode.com/svn/trunk/ mock-read-only``

If you have pip, setuptools or distribute you can install mock with:

    | ``easy_install mock``
    | ``pip install mock``

Alternatively you can download the mock distribution from PyPI and after
unpacking run:

   ``python setup.py install``


Quick Guide
===========

:class:`Mock` objects create all attributes and methods as you access them and store
details of how they have been used. You can configure them, to specify return
values or limit what attributes are available, and then make assertions about
how they have been used:

.. doctest::

    >>> from mock import Mock
    >>> real = ProductionClass()
    >>> real.method = Mock(return_value=3)
    >>> real.method(3, 4, 5, key='value')
    3
    >>> real.method.assert_called_with(3, 4, 5, key='value')

``side_effect`` allows you to perform side effects, return different values or
raise an exception when a mock is called:

.. doctest::

   >>> from mock import Mock
   >>> mock = Mock(side_effect=KeyError('foo'))
   >>> mock()
   Traceback (most recent call last):
    ...
   KeyError: 'foo'
   >>> values = [1, 2, 3]
   >>> def side_effect():
   ...     return values.pop()
   ...      
   >>> mock.side_effect = side_effect
   >>> mock(), mock(), mock()
   (3, 2, 1)

Mock has many other ways you can configure it and control its behaviour. For
example the ``spec`` argument configures the mock to take its specification from
another object. Attempting to access attributes or methods on the mock that
don't exist on the spec will fail with an ``AttributeError``.

The :func:`patch` decorator / context manager makes it easy to mock classes or
objects in a module under test. The object you specify will be replaced with a
mock (or other object) during the test and restored when the test ends:

.. doctest::
   
    >>> from mock import patch
    >>> @patch('test_module.ClassName1')
    ... @patch('test_module.ClassName2')
    ... def test(MockClass1, MockClass2):
    ...     test_module.ClassName1()
    ...     test_module.ClassName2()
    
    ...     assert MockClass1.called
    ...     assert MockClass2.called
    ... 
    >>> test()
    
    >>> with patch.object(ProductionClass, 'method') as mock_method:
    ...     mock_method.return_value = None
    ...     real = ProductionClass()
    ...     real.method(1, 2, 3)
    ...
    >>> mock_method.assert_called_with(1, 2, 3)


There is also :func:`patch.dict` for setting values in a dictionary just
during a scope and restoring the dictionary to its original state when the test
ends:

.. doctest::

   >>> foo = {'key': 'value'}
   >>> original = foo.copy()
   >>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
   ...     assert foo == {'newkey': 'newvalue'}
   ...
   >>> assert foo == original

Mock supports the mocking of Python `magic methods <magicmock.html>`_. The
easiest way of using magic methods is with the :class:`MagicMock` class. It
allows you to do things like:

.. doctest::

    >>> from mock import MagicMock
    >>> mock = MagicMock()
    >>> mock.__str__.return_value = 'foobarbaz'
    >>> str(mock)
    'foobarbaz'
    >>> mock.__str__.assert_called_with()

Mock allows you to assign functions (or other Mock instances) to magic methods
and they will be called appropriately. The MagicMock class is just a Mock
variant that has all of the magic methods pre-created for you (well - all the
useful ones anyway).

The following is an example of using magic methods with the ordinary Mock
class:

.. doctest::

    >>> from mock import Mock
    >>> mock = Mock()
    >>> mock.__str__ = Mock()
    >>> mock.__str__.return_value = 'wheeeeee'
    >>> str(mock)
    'wheeeeee'

:func:`mocksignature` is a useful companion to Mock and patch. It creates
copies of functions that delegate to a mock, but have the same signature as the
original function. This ensures that your mocks will fail in the same way as
your production code if they are called incorrectly:

.. doctest::

   >>> from mock import mocksignature
   >>> def function(a, b, c):
   ...     pass
   ... 
   >>> function2 = mocksignature(function)
   >>> function2.mock.return_value = 'fishy'
   >>> function2(1, 2, 3)
   'fishy'
   >>> function2.mock.assert_called_with(1, 2, 3)
   >>> function2('wrong arguments')
   Traceback (most recent call last):
    ...
   TypeError: <lambda>() takes exactly 3 arguments (1 given)

    
References
==========

Articles and blog entries on testing with Mock:

* `Mock recipes <http://konryd.blogspot.com/2010/06/mock-recipies.html>`_
* `Mockity mock mock - some love for the mock module <http://konryd.blogspot.com/2010/05/mockity-mock-mock-some-love-for-mock.html>`_
* `Python Unit Testing with Mock <http://www.insomnihack.com/?p=194>`_
* `Python mock testing techniques and tools <http://agiletesting.blogspot.com/2009/07/python-mock-testing-techniques-and.html>`_
* `How To Test Django Template Tags <http://techblog.ironfroggy.com/2008/10/how-to-test.html>`_
* `A presentation on Unit Testing with Mock <http://pypap.blogspot.com/2008/10/newbie-nugget-unit-testing-with-mock.html>`_
* `Mocking with Django and Google AppEngine <http://michael-a-nelson.blogspot.com/2008/09/mocking-with-django-and-google-app.html>`_


Tests
=====

Mock uses `unittest2 <http://pypi.python.org/pypi/unittest2>`_ for its own
test suite. In order to run it, use the ``unit2`` script that comes with
``unittest2`` module on a checkout of the source repository:

   ``unit2 discover``

On Python 2.7 and 3.2 you can use ``unittest`` module from the standard library.

   ``python3.2 -m unittest discover``

On Python 2.4 you will see one failure - testwith.py will fail to import as it
uses the ``with`` statement which is invalid syntax under Python 2.4.

On Python 3 the tests for unicode are skipped as they are not relevant.


Older Versions
==============

Documentation for older versions of mock:

* `mock 0.6.0 <http://www.voidspace.org.uk/python/mock/0.6.0/>`_
