====================================
 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


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


``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.

The ``mock`` module 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.

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.


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

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


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

.. toctree::
   :maxdepth: 2

   getting-started
   examples
   todo
   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``

    

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.

All Python versions except 2.6 & 2.7 will have at least one skip due to
tests using unsupported functionality, or on Python 3 the tests for unicode
not being relevant.


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

Documentation for older versions of mock:

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