diff -r 000000000000 -r 6474c204b198 python/mock-1.0.0/html/_sources/index.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/python/mock-1.0.0/html/_sources/index.txt Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,411 @@ +==================================== + Mock - Mocking and Testing Library +==================================== + +.. currentmodule:: mock + +:Author: `Michael Foord + `_ +:Version: |release| +:Date: 2012/10/07 +:Homepage: `Mock Homepage`_ +:Download: `Mock on PyPI`_ +:Documentation: `PDF Documentation + `_ +:License: `BSD License`_ +:Support: `Mailing list (testing-in-python@lists.idyll.org) + `_ +:Issue tracker: `Google code project + `_ + +.. _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. + +.. index:: introduction + +mock is a library for testing in Python. It allows you to replace parts of +your system under test with mock objects and make assertions about how they +have been used. + +mock is now part of the Python standard library, available as `unittest.mock +`_ +in Python 3.3 onwards. + +mock provides a core :class:`Mock` class removing the need to create a host +of 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 needed attributes in +the normal way. + +Additionally, mock 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 :class:`Mock`, :class:`MagicMock` and +:func:`patch`. + +Mock is very easy to use and is designed for use with +`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, Python 3 plus the latest versions of +Jython and PyPy. + + +.. testsetup:: + + class ProductionClass(object): + def method(self, *args): + pass + + module = sys.modules['module'] = ProductionClass + ProductionClass.ClassName1 = ProductionClass + ProductionClass.ClassName2 = ProductionClass + + + +API Documentation +================= + +.. toctree:: + :maxdepth: 2 + + mock + patch + helpers + sentinel + magicmock + + +User Guide +========== + +.. toctree:: + :maxdepth: 2 + + getting-started + examples + compare + changelog + + +.. index:: installing + +Installing +========== + +The current version is |release|. Mock is stable and widely used. If you do +find any bugs, or have suggestions for improvements / extensions +then please contact us. + +* `mock on PyPI `_ +* `mock documentation as PDF + `_ +* `Google Code Home & Mercurial Repository `_ + +.. index:: repository +.. index:: hg + +You can checkout the latest development version from the Google Code Mercurial +repository with the following command: + + ``hg clone https://mock.googlecode.com/hg/ mock`` + + +.. index:: pip +.. index:: easy_install +.. index:: setuptools + +If you have pip, setuptools or distribute you can install mock with: + + | ``easy_install -U mock`` + | ``pip install -U mock`` + +Alternatively you can download the mock distribution from PyPI and after +unpacking run: + + ``python setup.py install`` + + +Quick Guide +=========== + +:class:`Mock` and :class:`MagicMock` 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 MagicMock + >>> thing = ProductionClass() + >>> thing.method = MagicMock(return_value=3) + >>> thing.method(3, 4, 5, key='value') + 3 + >>> thing.method.assert_called_with(3, 4, 5, key='value') + +:attr:`side_effect` allows you to perform side effects, including raising an +exception when a mock is called: + +.. doctest:: + + >>> mock = Mock(side_effect=KeyError('foo')) + >>> mock() + Traceback (most recent call last): + ... + KeyError: 'foo' + + >>> values = {'a': 1, 'b': 2, 'c': 3} + >>> def side_effect(arg): + ... return values[arg] + ... + >>> mock.side_effect = side_effect + >>> mock('a'), mock('b'), mock('c') + (1, 2, 3) + >>> mock.side_effect = [5, 4, 3, 2, 1] + >>> mock(), mock(), mock() + (5, 4, 3) + +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('module.ClassName2') + ... @patch('module.ClassName1') + ... def test(MockClass1, MockClass2): + ... module.ClassName1() + ... module.ClassName2() + + ... assert MockClass1 is module.ClassName1 + ... assert MockClass2 is module.ClassName2 + ... assert MockClass1.called + ... assert MockClass2.called + ... + >>> test() + +.. note:: + + When you nest patch decorators the mocks are passed in to the decorated + function in the same order they applied (the normal *python* order that + decorators are applied). This means from the bottom up, so in the example + above the mock for `module.ClassName1` is passed in first. + + With `patch` it matters that you patch objects in the namespace where they + are looked up. This is normally straightforward, but for a quick guide + read :ref:`where to patch `. + +As well as a decorator `patch` can be used as a context manager in a with +statement: + +.. doctest:: + + >>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method: + ... thing = ProductionClass() + ... thing.method(1, 2, 3) + ... + >>> mock_method.assert_called_once_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 :ref:`magic methods `. The +easiest way of using magic methods is with the :class:`MagicMock` class. It +allows you to do things like: + +.. doctest:: + + >>> 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:: + + >>> mock = Mock() + >>> mock.__str__ = Mock(return_value='wheeeeee') + >>> str(mock) + 'wheeeeee' + +For ensuring that the mock objects in your tests have the same api as the +objects they are replacing, you can use :ref:`auto-speccing `. +Auto-speccing can be done through the `autospec` argument to patch, or the +:func:`create_autospec` function. Auto-speccing creates mock objects that +have the same attributes and methods as the objects they are replacing, and +any functions and methods (including constructors) have the same call +signature as the real object. + +This ensures that your mocks will fail in the same way as your production +code if they are used incorrectly: + +.. doctest:: + + >>> from mock import create_autospec + >>> def function(a, b, c): + ... pass + ... + >>> mock_function = create_autospec(function, return_value='fishy') + >>> mock_function(1, 2, 3) + 'fishy' + >>> mock_function.assert_called_once_with(1, 2, 3) + >>> mock_function('wrong arguments') + Traceback (most recent call last): + ... + TypeError: () takes exactly 3 arguments (1 given) + +`create_autospec` can also be used on classes, where it copies the signature of +the `__init__` method, and on callable objects where it copies the signature of +the `__call__` method. + + +.. index:: references +.. index:: articles + +References +========== + +Articles, blog entries and other stuff related to testing with Mock: + +* `Imposing a No DB Discipline on Django unit tests + `_ +* `mock-django: tools for mocking the Django ORM and models + `_ +* `PyCon 2011 Video: Testing with mock `_ +* `Mock objects in Python + `_ +* `Python: Injecting Mock Objects for Powerful Testing + `_ +* `Python Mock: How to assert a substring of logger output + `_ +* `Mocking Django `_ +* `Mocking dates and other classes that can't be modified + `_ +* `Mock recipes `_ +* `Mockity mock mock - some love for the mock module + `_ +* `Coverage and Mock (with django) + `_ +* `Python Unit Testing with Mock `_ +* `Getting started with Python Mock + `_ +* `Smart Parameter Checks with mock + `_ +* `Python mock testing techniques and tools + `_ +* `How To Test Django Template Tags + `_ +* `A presentation on Unit Testing with Mock + `_ +* `Mocking with Django and Google AppEngine + `_ + + +.. index:: tests +.. index:: unittest2 + +Tests +===== + +Mock uses `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` + +If you have `setuptools `_ as well as +unittest2 you can run: + + ``python setup.py test`` + +On Python 3.2 you can use ``unittest`` module from the standard library. + + ``python3.2 -m unittest discover`` + +.. index:: Python 3 + +On Python 3 the tests for unicode are skipped as they are not relevant. On +Python 2.4 tests that use the with statements are skipped as the with statement +is invalid syntax on Python 2.4. + + +.. index:: older versions + +Older Versions +============== + +Documentation for older versions of mock: + +* `mock 0.8 `_ +* `mock 0.7 `_ +* `mock 0.6 `_ + +Docs from the in-development version of `mock` can be found at +`mock.readthedocs.org `_. + + +Terminology +=========== + +Terminology for objects used to replace other ones can be confusing. Terms +like double, fake, mock, stub, and spy are all used with varying meanings. + +In `classic mock terminology +`_ +:class:`mock.Mock` is a `spy `_ that +allows for *post-mortem* examination. This is what I call the "action -> +assertion" [#]_ pattern of testing. + +I'm not however a fan of this "statically typed mocking terminology" +promulgated by `Martin Fowler +`_. It confuses usage +patterns with implementation and prevents you from using natural terminology +when discussing mocking. + +I much prefer duck typing, if an object used in your test suite looks like a +mock object and quacks like a mock object then it's fine to call it a mock, no +matter what the implementation looks like. + +This terminology is perhaps more useful in less capable languages where +different usage patterns will *require* different implementations. +`mock.Mock()` is capable of being used in most of the different roles +described by Fowler, except (annoyingly / frustratingly / ironically) a Mock +itself! + +How about a simpler definition: a "mock object" is an object used to replace a +real one in a system under test. + +.. [#] This pattern is called "AAA" by some members of the testing community; + "Arrange - Act - Assert".