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].
+>>> def __str__(self):
+... return 'fooble'
+...
+>>> mock = Mock()
+>>> mock.__str__ = __str__
+>>> str(mock)
+'fooble'
+
+>>> mock = Mock()
+>>> mock.__str__ = Mock()
+>>> mock.__str__.return_value = 'fooble'
+>>> str(mock)
+'fooble'
+
+>>> 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:
+>>> mock = Mock()
+>>> mock.__enter__ = Mock(return_value='foo')
+>>> mock.__exit__ = Mock(return_value=False)
+>>> with mock as m:
+... assert m == 'foo'
+...
+>>> mock.__enter__.assert_called_with()
+>>> mock.__exit__.assert_called_with(None, None, None)
+Calls to magic methods do not appear in method_calls, but they +are recorded in mock_calls.
+Note
+If you use the spec keyword argument to create a mock then attempting to +set a magic method that isn’t in the spec will raise an AttributeError.
+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 are either in use by +mock, can’t be set dynamically, or can cause problems:
+There are two MagicMock variants: MagicMock and NonCallableMagicMock.
+MagicMock is a subclass of Mock with default implementations +of most of the magic methods. You can use MagicMock without having to +configure the magic methods yourself.
+The constructor parameters have the same meaning as for Mock.
+If you use the spec or spec_set arguments then only magic methods +that exist in the spec will be created.
+A non-callable version of MagicMock.
+The constructor parameters have the same meaning as for +MagicMock, with the exception of return_value and +side_effect which have no meaning on a non-callable mock.
+The magic methods are setup with MagicMock objects, so you can configure them +and use them in the usual way:
+>>> 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:
+>>> mock = MagicMock()
+>>> int(mock)
+1
+>>> len(mock)
+0
+>>> hex(mock)
+'0x1'
+>>> list(mock)
+[]
+>>> object() in mock
+False
+The two equality method, __eq__ and __ne__, are special (changed in +0.7.2). They do the default equality comparison on identity, using a side +effect, unless you change their return value to return something else:
+>>> MagicMock() == 3
+False
+>>> MagicMock() != 3
+True
+>>> mock = MagicMock()
+>>> mock.__eq__.return_value = True
+>>> mock == 3
+True
+In 0.8 the __iter__ also gained special handling implemented with a +side effect. The return value of MagicMock.__iter__ can be any iterable +object and isn’t required to be an iterator:
+>>> mock = MagicMock()
+>>> mock.__iter__.return_value = ['a', 'b', 'c']
+>>> list(mock)
+['a', 'b', 'c']
+>>> list(mock)
+['a', 'b', 'c']
+If the return value is an iterator, then iterating over it once will consume +it and subsequent iterations will result in an empty list:
+>>> mock.__iter__.return_value = iter(['a', 'b', 'c'])
+>>> list(mock)
+['a', 'b', 'c']
+>>> list(mock)
+[]
+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. |