michael@0: mock is a library for testing in Python. It allows you to replace parts of michael@0: your system under test with mock objects and make assertions about how they michael@0: have been used. michael@0: michael@0: mock is now part of the Python standard library, available as `unittest.mock < michael@0: http://docs.python.org/py3k/library/unittest.mock.html#module-unittest.mock>`_ michael@0: in Python 3.3 onwards. michael@0: michael@0: mock provides a core `MagicMock` class removing the need to create a host of michael@0: stubs throughout your test suite. After performing an action, you can make michael@0: assertions about which methods / attributes were used and arguments they were michael@0: called with. You can also specify return values and set needed attributes in michael@0: the normal way. michael@0: michael@0: mock is tested on Python versions 2.4-2.7 and Python 3. mock is also tested michael@0: with the latest versions of Jython and pypy. michael@0: michael@0: The mock module also provides utility functions / objects to assist with michael@0: testing, particularly monkey patching. michael@0: michael@0: * `PDF documentation for 1.0 beta 1 michael@0: `_ michael@0: * `mock on google code (repository and issue tracker) michael@0: `_ michael@0: * `mock documentation michael@0: `_ michael@0: * `mock on PyPI `_ michael@0: * `Mailing list (testing-in-python@lists.idyll.org) michael@0: `_ michael@0: michael@0: Mock is very easy to use and is designed for use with michael@0: `unittest `_. Mock is based on michael@0: the 'action -> assertion' pattern instead of 'record -> replay' used by many michael@0: mocking frameworks. See the `mock documentation`_ for full details. michael@0: michael@0: Mock objects create all attributes and methods as you access them and store michael@0: details of how they have been used. You can configure them, to specify return michael@0: values or limit what attributes are available, and then make assertions about michael@0: how they have been used:: michael@0: michael@0: >>> from mock import Mock michael@0: >>> real = ProductionClass() michael@0: >>> real.method = Mock(return_value=3) michael@0: >>> real.method(3, 4, 5, key='value') michael@0: 3 michael@0: >>> real.method.assert_called_with(3, 4, 5, key='value') michael@0: michael@0: `side_effect` allows you to perform side effects, return different values or michael@0: raise an exception when a mock is called:: michael@0: michael@0: >>> mock = Mock(side_effect=KeyError('foo')) michael@0: >>> mock() michael@0: Traceback (most recent call last): michael@0: ... michael@0: KeyError: 'foo' michael@0: >>> values = {'a': 1, 'b': 2, 'c': 3} michael@0: >>> def side_effect(arg): michael@0: ... return values[arg] michael@0: ... michael@0: >>> mock.side_effect = side_effect michael@0: >>> mock('a'), mock('b'), mock('c') michael@0: (3, 2, 1) michael@0: >>> mock.side_effect = [5, 4, 3, 2, 1] michael@0: >>> mock(), mock(), mock() michael@0: (5, 4, 3) michael@0: michael@0: Mock has many other ways you can configure it and control its behaviour. For michael@0: example the `spec` argument configures the mock to take its specification from michael@0: another object. Attempting to access attributes or methods on the mock that michael@0: don't exist on the spec will fail with an `AttributeError`. michael@0: michael@0: The `patch` decorator / context manager makes it easy to mock classes or michael@0: objects in a module under test. The object you specify will be replaced with a michael@0: mock (or other object) during the test and restored when the test ends:: michael@0: michael@0: >>> from mock import patch michael@0: >>> @patch('test_module.ClassName1') michael@0: ... @patch('test_module.ClassName2') michael@0: ... def test(MockClass2, MockClass1): michael@0: ... test_module.ClassName1() michael@0: ... test_module.ClassName2() michael@0: michael@0: ... assert MockClass1.called michael@0: ... assert MockClass2.called michael@0: ... michael@0: >>> test() michael@0: michael@0: .. note:: michael@0: michael@0: When you nest patch decorators the mocks are passed in to the decorated michael@0: function in the same order they applied (the normal *python* order that michael@0: decorators are applied). This means from the bottom up, so in the example michael@0: above the mock for `test_module.ClassName2` is passed in first. michael@0: michael@0: With `patch` it matters that you patch objects in the namespace where they michael@0: are looked up. This is normally straightforward, but for a quick guide michael@0: read `where to patch michael@0: `_. michael@0: michael@0: As well as a decorator `patch` can be used as a context manager in a with michael@0: statement:: michael@0: michael@0: >>> with patch.object(ProductionClass, 'method') as mock_method: michael@0: ... mock_method.return_value = None michael@0: ... real = ProductionClass() michael@0: ... real.method(1, 2, 3) michael@0: ... michael@0: >>> mock_method.assert_called_once_with(1, 2, 3) michael@0: michael@0: There is also `patch.dict` for setting values in a dictionary just during the michael@0: scope of a test and restoring the dictionary to its original state when the michael@0: test ends:: michael@0: michael@0: >>> foo = {'key': 'value'} michael@0: >>> original = foo.copy() michael@0: >>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True): michael@0: ... assert foo == {'newkey': 'newvalue'} michael@0: ... michael@0: >>> assert foo == original michael@0: michael@0: Mock supports the mocking of Python magic methods. The easiest way of michael@0: using magic methods is with the `MagicMock` class. It allows you to do michael@0: things like:: michael@0: michael@0: >>> from mock import MagicMock michael@0: >>> mock = MagicMock() michael@0: >>> mock.__str__.return_value = 'foobarbaz' michael@0: >>> str(mock) michael@0: 'foobarbaz' michael@0: >>> mock.__str__.assert_called_once_with() michael@0: michael@0: Mock allows you to assign functions (or other Mock instances) to magic methods michael@0: and they will be called appropriately. The MagicMock class is just a Mock michael@0: variant that has all of the magic methods pre-created for you (well - all the michael@0: useful ones anyway). michael@0: michael@0: The following is an example of using magic methods with the ordinary Mock michael@0: class:: michael@0: michael@0: >>> from mock import Mock michael@0: >>> mock = Mock() michael@0: >>> mock.__str__ = Mock(return_value = 'wheeeeee') michael@0: >>> str(mock) michael@0: 'wheeeeee' michael@0: michael@0: For ensuring that the mock objects your tests use have the same api as the michael@0: objects they are replacing, you can use "auto-speccing". Auto-speccing can michael@0: be done through the `autospec` argument to patch, or the `create_autospec` michael@0: function. Auto-speccing creates mock objects that have the same attributes michael@0: and methods as the objects they are replacing, and any functions and methods michael@0: (including constructors) have the same call signature as the real object. michael@0: michael@0: This ensures that your mocks will fail in the same way as your production michael@0: code if they are used incorrectly:: michael@0: michael@0: >>> from mock import create_autospec michael@0: >>> def function(a, b, c): michael@0: ... pass michael@0: ... michael@0: >>> mock_function = create_autospec(function, return_value='fishy') michael@0: >>> mock_function(1, 2, 3) michael@0: 'fishy' michael@0: >>> mock_function.assert_called_once_with(1, 2, 3) michael@0: >>> mock_function('wrong arguments') michael@0: Traceback (most recent call last): michael@0: ... michael@0: TypeError: () takes exactly 3 arguments (1 given) michael@0: michael@0: `create_autospec` can also be used on classes, where it copies the signature of michael@0: the `__init__` method, and on callable objects where it copies the signature of michael@0: the `__call__` method. michael@0: michael@0: The distribution contains tests and documentation. The tests require michael@0: `unittest2 `_ to run. michael@0: michael@0: Docs from the in-development version of `mock` can be found at michael@0: `mock.readthedocs.org `_.