| Author: | Michael Foord | +
|---|---|
| Version: | 1.0.0 | +
| 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 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 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 patch() decorator that handles patching +module and class level attributes within the scope of a test, along with +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. 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.
+The current version is 1.0.0. Mock is stable and widely used. If you do +find any bugs, or have suggestions for improvements / extensions +then please contact us.
+ +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
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
Mock and 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:
+>>> 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')
+side_effect allows you to perform side effects, including raising an +exception when a mock is called:
+>>> 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 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:
+>>> 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 where to patch.
+As well as a decorator patch can be used as a context manager in a with +statement:
+>>> 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 patch.dict() for setting values in a dictionary just +during a scope and restoring the dictionary to its original state when the test +ends:
+>>> 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. The +easiest way of using magic methods is with the MagicMock class. It +allows you to do things like:
+>>> 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:
+>>> 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 auto-speccing. +Auto-speccing can be done through the autospec argument to patch, or the +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:
+>>> 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: <lambda>() 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.
+Articles, blog entries and other stuff related to testing with Mock:
+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
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.
+Documentation for older versions of mock:
+ +Docs from the in-development version of mock can be found at +mock.readthedocs.org.
+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 +mock.Mock is a spy that +allows for post-mortem examination. This is what I call the “action -> +assertion” [1] 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.
+| [1] | This pattern is called “AAA” by some members of the testing community; +“Arrange - Act - Assert”. |