Mock supports mocking magic methods. This allows mock objects to replace containers or other objects that implement Python protocols.
Because magic methods are looked up differently from normal methods [1], this support has been specially implemented. This means that only specific magic methods are supported. The supported list includes almost all of them. If there are any missing that you need please let us know!
You mock magic methods by setting the method you are interested in to a function or a mock instance. If you are using a function then it must take self as the first argument [2].
>>> from mock import Mock
>>> def __str__(self):
... return 'fooble'
...
>>> mock = Mock()
>>> mock.__str__ = __str__
>>> str(mock)
'fooble'
>>> from mock import Mock
>>> mock = Mock()
>>> mock.__str__ = Mock()
>>> mock.__str__.return_value = 'fooble'
>>> str(mock)
'fooble'
>>> from mock import Mock
>>> mock = Mock()
>>> mock.__iter__ = Mock(return_value=iter([]))
>>> list(mock)
[]
One use case for this is for mocking objects used as context managers in a with statement:
>>> from mock import Mock
>>> mock = Mock()
>>> mock.__enter__ = Mock()
>>> mock.__exit__ = Mock()
>>> mock.__exit__.return_value = False
>>> with mock:
... pass
...
>>> mock.__enter__.assert_called_with()
>>> mock.__exit__.assert_called_with(None, None, None)
Calls to magic methods do not (yet) appear in mock.Mock.method_calls. This may change in a future release.
The full list of supported magic methods is:
The following methods are supported in Python 2 but don’t exist in Python 3:
The following methods are supported in Python 3 but don’t exist in Python 2:
The following methods exist but are not supported as they either can’t be dynamically set or can cause problems:
The magic methods are setup with Mock objects, so you can configure them and use them in the usual way:
>>> from mock import MagicMock
>>> mock = MagicMock()
>>> mock[3] = 'fish'
>>> mock.__setitem__.assert_called_with(3, 'fish')
>>> mock.__getitem__.return_value = 'result'
>>> mock[2]
'result'
By default many of the protocol methods are required to return objects of a specific type. These methods are preconfigured with a default return value, so that they can be used without you having to do anything if you aren’t interested in the return value. You can still set the return value manually if you want to change the default.
Methods and their defaults:
For example:
>>> from mock import MagicMock
>>> mock = MagicMock()
>>> int(mock)
0
>>> len(mock)
0
>>> hex(mock)
'0x0'
>>> list(mock)
[]
>>> object() in mock
False
MagicMock has all of the supported magic methods configured except for some of the obscure and obsolete ones. You can still set these up if you want.
Magic methods that are supported but not setup by default in MagicMock are:
[1] | Magic methods should be looked up on the class rather than the instance. Different versions of Python are inconsistent about applying this rule. The supported protocol methods should work with all supported versions of Python. |
[2] | The function is basically hooked up to the class, but each Mock instance is kept isolated from the others. |