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

:Author: `Michael Foord <http://www.voidspace.org.uk/python/weblog/index.shtml>`_
:Version: Mock 0.6.0
:Date: 2009/08/22
:Homepage: `Mock Homepage`_
: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>`_
:Contact: fuzzyman@voidspace.org.uk

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


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


Introduction
============

``mock`` provides a core :class:`mock.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.

It also provides a :func:`mock.patch` decorator that handles patching module and class
level attributes within the scope of a test, along with :const:`mock.sentinel` for 
creating unique objects.

Most mocking libraries follow the 'record -> replay' pattern of mocking. Mock
uses the 'action -> assertion' pattern, which is more readable and intuitive;
particularly when working with the Python `unittest module
<http://docs.python.org/lib/module-unittest.html>`_. For a discussion of the
merits of the two approaches, see `Mocking, Patching, Stubbing: all that Stuff
<http://www.voidspace.org.uk/python/articles/mocking.shtml>`_.


Downloading
===========

The current version is **0.6.0**, dated 23rd August 2009. Mock is still 
experimental; the API may change. If you find bugs or 
have suggestions for improvements / extensions then please email me.

* `mock.py (module only) <http://www.voidspace.org.uk/downloads/mock.py>`_
* `mock-0.6.0.zip (module, tests and documentation) <http://www.voidspace.org.uk/downloads/mock-0.6.0.zip>`_
* `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``

Mock is registered with PyPi (`Mock on PyPi <http://pypi.python.org/pypi/mock/>`_). 
If you have pip, setuptools or Distribute you can install mock with:

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

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

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


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

.. toctree::
   :maxdepth: 2

   getting-started
   examples
   todo
   changelog


References
==========

Articles and blog entries on testing with Mock:


* `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 the `discover module <http://pypi.python.org/pypi/discover>`_ to
collect and run its tests. discover.py is included in the subversion repository
so from a fresh checkout you can execute the following to run all the tests:

   ``python discover.py``
   
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.