unittest.mock —- mock对象库

3.3 新版功能.

源代码： Lib/unittest/mock.py

unittest.mock 是一个用于测试的Python库。它允许使用mock对象替换受测试系统的部分，并对它们如何已经被使用进行断言。

unittest.mock 提供的 Mock 类，能在整个测试套件中模拟大量的方法。创建后，就可以断言调用了哪些方法/属性及其参数。还可以以常规方式指定返回值并设置所需的属性。

此外，mock 提供了用于修补测试范围内模块和类级别属性的 patch() 装饰器，和用于创建独特对象的 sentinel 。 阅读 quick guide 中的案例了解如何使用 Mock ，MagicMock 和 patch() 。

Mock is designed for use with unittest and is based on the ‘action -> assertion’ pattern instead of ‘record -> replay’ used by many mocking frameworks.

在 Python 的早期版本要单独使用 unittest.mock ，在 PyPI 获取 mock 。

快速上手

当您访问对象时， Mock 和 MagicMock 将创建所有属性和方法，并保存他们在使用时的细节。你可以通过配置，指定返回值或者限制可访问属性，然后断言他们如何被调用：

>>> from unittest.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 设置副作用(side effects) ，可以是一个 mock 被调用是抛出的异常：

>>> 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 还可以通过其他方法配置和控制其行为。例如 mock 可以通过设置 spec 参数来从一个对象中获取其规格(specification)。如果访问 mock 的属性或方法不在 spec 中，会报 AttributeError 错误。

使用 patch() 装饰去/上下文管理器，可以更方便地测试一个模块下的类或对象。你指定的对象会在测试过程中替换成 mock （或者其他对象），测试结束后恢复。

>>> from unittest.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()

注解

当你嵌套 patch 装饰器时，mock 将以执行顺序传递给装饰器函数（Python 装饰器正常顺序）。由于从下至上，因此在上面的示例中，首先 mock 传入的 module.ClassName1 。

在查找对象的名称空间中修补对象使用 patch() 。使用起来很简单，阅读 在哪里打补丁 来快速上手。

patch() 也可以 with 语句中使用上下文管理。

>>> 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)

还有一个 patch.dict() 用于在一定范围内设置字典中的值，并在测试结束时将字典恢复为其原始状态：

>>> foo = {'key': 'value'}
>>> original = foo.copy()
>>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
...     assert foo == {'newkey': 'newvalue'}
...
>>> assert foo == original

Mock支持 Python 魔术方法 。使用模式方法最简单的方式是使用 MagicMock class. 。它可以做如下事情：

>>> mock = MagicMock()
>>> mock.__str__.return_value = 'foobarbaz'
>>> str(mock)
'foobarbaz'
>>> mock.__str__.assert_called_with()

Mock 能指定函数（或其他 Mock 实例）为魔术方法，它们将被适当地调用。 MagicMock 是预先创建了所有魔术方法（所有有用的方法） 的 Mock 。

下面是一个使用了普通 Mock 类的魔术方法的例子

>>> mock = Mock()
>>> mock.__str__ = Mock(return_value='wheeeeee')
>>> str(mock)
'wheeeeee'

使用 auto-speccing 可以保证测试中的模拟对象与要替换的对象具有相同的api 。在 patch 中可以通过 autospec 参数实现自动推断，或者使用 create_autospec() 函数。自动推断会创建一个与要替换对象相同的属相和方法的模拟对象，并且任何函数和方法（包括构造函数）都具有与真实对象相同的调用签名。

这么做是为了因确保不当地使用 mock 导致与生产代码相同的失败：

>>> from unittest.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() 时，会复制 __init__ 方法的签名，另外在可调用对象上使用时，会复制 __call__ 方法的签名。

Mock 类

Mock 是一个可以灵活的替换存根 (stubs) 的对象，可以测试所有代码。 Mock 是可调用的，在访问其属性时创建一个新的 mock 1 。访问相同的属性只会返回相同的 mock 。 Mock 会保存调用记录，可以通过断言获悉代码的调用。

MagicMock 是 Mock 的子类，它有所有预创建且可使用的魔术方法。在需要模拟不可调用对象时，可以使用 NonCallableMock 和 NonCallableMagicMock

patch() 装饰器便于 Mock 对象临时替换特定模块中的类。 patch() 默认创建 MagicMock 。可以使用 patch() 方法的 new_callable 参数指定 Mock 的替代类。

class unittest.mock.Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, \*kwargs*)

创建一个新的 Mock 对象。通过可选参数指定 Mock 对象的行为：

• spec: 可以是要给字符串列表，也可以是充当模拟对象规范的现有对象（类或实例）。如果传入一个对象，则通过在该对象上调用 dir 来生成字符串列表（不支持的魔法属性和方法除外）。访问不在此列表中的任何属性都将触发 AttributeError 。

  如果 spec 是一个对象（而不是字符串列表），则 __class__ 返回 spec 对象的类。 这允许模拟程序通过 isinstance() 测试。

• spec_set ：spec 的更严格的变体。如果使用了该属性，尝试模拟 set 或 get 的属性不在 spec_set 所包含的对象中时，会抛出 AttributeError 。

• side_effect ：每当调用 Mock 时都会调用的函数。 参见 side_effect 属性。 对于引发异常或动态更改返回值很有用。 该函数使用与 mock 函数相同的参数调用，并且除非返回 DEFAULT ，否则该函数的返回值将用作返回值。

  另外， side_effect 可以是异常类或实例。 此时，调用模拟程序时将引发异常。

  如果 side_effect 是可迭代对象，则每次调用 mock 都将返回可迭代对象的下一个值。

  设置 side_effect 为 None 即可清空。

• return_value ：调用 mock 的返回值。 默认情况下，是一个新的Mock（在首次访问时创建）。 参见 return_value 属性 。

• unsafe ：默认情况下，如果任何以 assert 或 assret 开头的属性都将引发 AttributeError 。 当 unsafe=True 时可以访问。

  3.5 新版功能.

• wraps ：要包装的 mock 对象。 如果 wraps 不是 None ，那么调用 Mock 会将调用传递给 wraps 的对象（返回实际结果）。 对模拟的属性访问将返回一个 Mock 对象，该对象包装了 wraps 对象的相应属性（因此，尝试访问不存在的属性将引发 AttributeError ）。

  如果明确指定 return_value ，调用是，不会返回包装对象，而是返回 return_value 。

• name ：mock 的名称。 在调试时很有用。 名称会传递到子 mock 。

还可以使用任意关键字参数来调用 mock 。 创建模拟后，将使用这些属性来设置 mock 的属性。 有关详细信息，请参见 configure_mock() 方法。

• assert_called()

  断言至少被调用过一次。

  >>> mock = Mock()
  >>> mock.method()
  <Mock name='mock.method()' id='...'>
  >>> mock.method.assert_called()

  3.6 新版功能.

• assert_called_once()

  断言仅被调用一次。

  >>> mock = Mock()
  >>> mock.method()
  <Mock name='mock.method()' id='...'>
  >>> mock.method.assert_called_once()
  >>> mock.method()
  <Mock name='mock.method()' id='...'>
  >>> mock.method.assert_called_once()
  Traceback (most recent call last):
  ...
  AssertionError: Expected 'method' to have been called once. Called 2 times.

  3.6 新版功能.

• assert_called_with(\args, **kwargs*)

  此方法是断言上次调用已以特定方式进行的一种便捷方法：

  >>> mock = Mock()
  >>> mock.method(1, 2, 3, test='wow')
  <Mock name='mock.method()' id='...'>
  >>> mock.method.assert_called_with(1, 2, 3, test='wow')

• assert_called_once_with(\args, **kwargs*)

  Assert that the mock was called exactly once and that call was with the specified arguments.

  >>> mock = Mock(return_value=None)
  >>> mock('foo', bar='baz')
  >>> mock.assert_called_once_with('foo', bar='baz')
  >>> mock('other', bar='values')
  >>> mock.assert_called_once_with('other', bar='values')
  Traceback (most recent call last):
    ...
  AssertionError: Expected 'mock' to be called once. Called 2 times.

• assert_any_call(\args, **kwargs*)

  断言使用指定的参数调用。

  The assert passes if the mock has ever been called, unlike assert_called_with() and assert_called_once_with() that only pass if the call is the most recent one, and in the case of assert_called_once_with() it must also be the only call.

  >>> mock = Mock(return_value=None)
  >>> mock(1, 2, arg='thing')
  >>> mock('some', 'thing', 'else')
  >>> mock.assert_any_call(1, 2, arg='thing')

• assert_has_calls(calls, any_order=False)

  assert the mock has been called with the specified calls. The mock_calls list is checked for the calls.

  If any_order is false then the calls must be sequential. There can be extra calls before or after the specified calls.

  If any_order is true then the calls can be in any order, but they must all appear in mock_calls.

  >>> mock = Mock(return_value=None)
  >>> mock(1)
  >>> mock(2)
  >>> mock(3)
  >>> mock(4)
  >>> calls = [call(2), call(3)]
  >>> mock.assert_has_calls(calls)
  >>> calls = [call(4), call(2), call(3)]
  >>> mock.assert_has_calls(calls, any_order=True)

• assert_not_called()

  Assert the mock was never called.

  >>> m = Mock()
  >>> m.hello.assert_not_called()
  >>> obj = m.hello()
  >>> m.hello.assert_not_called()
  Traceback (most recent call last):
    ...
  AssertionError: Expected 'hello' to not have been called. Called 1 times.

  3.5 新版功能.

• reset_mock(**, return_value=False, side_effect=False*)

  The reset_mock method resets all the call attributes on a mock object:

  >>> mock = Mock(return_value=None)
  >>> mock('hello')
  >>> mock.called
  True
  >>> mock.reset_mock()
  >>> mock.called
  False

  在 3.6 版更改: Added two keyword only argument to the reset_mock function.

  This can be useful where you want to make a series of assertions that reuse the same object. Note that reset_mock() doesn’t clear the return value, side_effect or any child attributes you have set using normal assignment by default. In case you want to reset return_value or side_effect, then pass the corresponding parameter as True. Child mocks and the return value mock (if any) are reset as well.

  注解

  return_value, and side_effect are keyword only argument.

• mock_add_spec(spec, spec_set=False)

  Add a spec to a mock. spec can either be an object or a list of strings. Only attributes on the spec can be fetched as attributes from the mock.

  If spec_set is true then only attributes on the spec can be set.

• attach_mock(mock, attribute)

  Attach a mock as an attribute of this one, replacing its name and parent. Calls to the attached mock will be recorded in the method_calls and mock_calls attributes of this one.

• configure_mock(\*kwargs*)

  Set attributes on the mock through keyword arguments.

  Attributes plus return values and side effects can be set on child mocks using standard dot notation and unpacking a dictionary in the method call:

  >>> mock = Mock()
  >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
  >>> mock.configure_mock(**attrs)
  >>> mock.method()
  3
  >>> mock.other()
  Traceback (most recent call last):
    ...
  KeyError

  The same thing can be achieved in the constructor call to mocks:

  >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
  >>> mock = Mock(some_attribute='eggs', **attrs)
  >>> mock.some_attribute
  'eggs'
  >>> mock.method()
  3
  >>> mock.other()
  Traceback (most recent call last):
    ...
  KeyError

  configure_mock() exists to make it easier to do configuration after the mock has been created.

• __dir__()

  Mock objects limit the results of dir(some_mock) to useful results. For mocks with a spec this includes all the permitted attributes for the mock.

  See FILTER_DIR for what this filtering does, and how to switch it off.

• _get_child_mock(\*kw*)

  Create the child mocks for attributes and return value. By default child mocks will be the same type as the parent. Subclasses of Mock may want to override this to customize the way child mocks are made.

  For non-callable mocks the callable variant will be used (rather than any custom subclass).

• called

  A boolean representing whether or not the mock object has been called:

  >>> mock = Mock(return_value=None)
  >>> mock.called
  False
  >>> mock()
  >>> mock.called
  True

• call_count

  An integer telling you how many times the mock object has been called:

  >>> mock = Mock(return_value=None)
  >>> mock.call_count
  0
  >>> mock()
  >>> mock()
  >>> mock.call_count
  2

• return_value

  Set this to configure the value returned by calling the mock:

  >>> mock = Mock()
  >>> mock.return_value = 'fish'
  >>> mock()
  'fish'

  The default return value is a mock object and you can configure it in the normal way:

  >>> mock = Mock()
  >>> mock.return_value.attribute = sentinel.Attribute
  >>> mock.return_value()
  <Mock name='mock()()' id='...'>
  >>> mock.return_value.assert_called_with()

  return_value can also be set in the constructor:

  >>> mock = Mock(return_value=3)
  >>> mock.return_value
  3
  >>> mock()
  3

• side_effect

  This can either be a function to be called when the mock is called, an iterable or an exception (class or instance) to be raised.

  If you pass in a function it will be called with same arguments as the mock and unless the function returns the DEFAULT singleton the call to the mock will then return whatever the function returns. If the function returns DEFAULT then the mock will return its normal value (from the return_value).

  If you pass in an iterable, it is used to retrieve an iterator which must yield a value on every call. This value can either be an exception instance to be raised, or a value to be returned from the call to the mock (DEFAULT handling is identical to the function case).

  An example of a mock that raises an exception (to test exception handling of an API):

  >>> mock = Mock()
  >>> mock.side_effect = Exception('Boom!')
  >>> mock()
  Traceback (most recent call last):
    ...
  Exception: Boom!

  Using side_effect to return a sequence of values:

  >>> mock = Mock()
  >>> mock.side_effect = [3, 2, 1]
  >>> mock(), mock(), mock()
  (3, 2, 1)

  Using a callable:

  >>> mock = Mock(return_value=3)
  >>> def side_effect(*args, **kwargs):
  ...     return DEFAULT
  ...
  >>> mock.side_effect = side_effect
  >>> mock()
  3

  side_effect can be set in the constructor. Here’s an example that adds one to the value the mock is called with and returns it:

  >>> side_effect = lambda value: value + 1
  >>> mock = Mock(side_effect=side_effect)
  >>> mock(3)
  4
  >>> mock(-8)
  -7

  Setting side_effect to None clears it:

  >>> m = Mock(side_effect=KeyError, return_value=3)
  >>> m()
  Traceback (most recent call last):
   ...
  KeyError
  >>> m.side_effect = None
  >>> m()
  3

• call_args

  This is either None (if the mock hasn’t been called), or the arguments that the mock was last called with. This will be in the form of a tuple: the first member, which can also be accessed through the args property, is any ordered arguments the mock was called with (or an empty tuple) and the second member, which can also be accessed through the kwargs property, is any keyword arguments (or an empty dictionary).

  >>> mock = Mock(return_value=None)
  >>> print(mock.call_args)
  None
  >>> mock()
  >>> mock.call_args
  call()
  >>> mock.call_args == ()
  True
  >>> mock(3, 4)
  >>> mock.call_args
  call(3, 4)
  >>> mock.call_args == ((3, 4),)
  True
  >>> mock.call_args.args
  (3, 4)
  >>> mock.call_args.kwargs
  {}
  >>> mock(3, 4, 5, key='fish', next='w00t!')
  >>> mock.call_args
  call(3, 4, 5, key='fish', next='w00t!')
  >>> mock.call_args.args
  (3, 4, 5)
  >>> mock.call_args.kwargs
  {'key': 'fish', 'next': 'w00t!'}

  call_args, along with members of the lists call_args_list, method_calls and mock_calls are call objects. These are tuples, so they can be unpacked to get at the individual arguments and make more complex assertions. See calls as tuples.

  在 3.8 版更改: Added args and kwargs properties.

• call_args_list

  This is a list of all the calls made to the mock object in sequence (so the length of the list is the number of times it has been called). Before any calls have been made it is an empty list. The call object can be used for conveniently constructing lists of calls to compare with call_args_list.

  >>> mock = Mock(return_value=None)
  >>> mock()
  >>> mock(3, 4)
  >>> mock(key='fish', next='w00t!')
  >>> mock.call_args_list
  [call(), call(3, 4), call(key='fish', next='w00t!')]
  >>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)]
  >>> mock.call_args_list == expected
  True

  Members of call_args_list are call objects. These can be unpacked as tuples to get at the individual arguments. See calls as tuples.

• method_calls

  As well as tracking calls to themselves, mocks also track calls to methods and attributes, and their methods and attributes:

  >>> mock = Mock()
  >>> mock.method()
  <Mock name='mock.method()' id='...'>
  >>> mock.property.method.attribute()
  <Mock name='mock.property.method.attribute()' id='...'>
  >>> mock.method_calls
  [call.method(), call.property.method.attribute()]

  Members of method_calls are call objects. These can be unpacked as tuples to get at the individual arguments. See calls as tuples.

• mock_calls

  mock_calls records all calls to the mock object, its methods, magic methods and return value mocks.

  >>> mock = MagicMock()
  >>> result = mock(1, 2, 3)
  >>> mock.first(a=3)
  <MagicMock name='mock.first()' id='...'>
  >>> mock.second()
  <MagicMock name='mock.second()' id='...'>
  >>> int(mock)
  1
  >>> result(1)
  <MagicMock name='mock()()' id='...'>
  >>> expected = [call(1, 2, 3), call.first(a=3), call.second(),
  ... call.__int__(), call()(1)]
  >>> mock.mock_calls == expected
  True

  Members of mock_calls are call objects. These can be unpacked as tuples to get at the individual arguments. See calls as tuples.

  注解

  The way mock_calls are recorded means that where nested calls are made, the parameters of ancestor calls are not recorded and so will always compare equal:

  >>> mock = MagicMock()
  >>> mock.top(a=3).bottom()
  <MagicMock name='mock.top().bottom()' id='...'>
  >>> mock.mock_calls
  [call.top(a=3), call.top().bottom()]
  >>> mock.mock_calls[-1] == call.top(a=-1).bottom()
  True

• __class__

  Normally the __class__ attribute of an object will return its type. For a mock object with a spec, __class__ returns the spec class instead. This allows mock objects to pass isinstance() tests for the object they are replacing / masquerading as:

  >>> mock = Mock(spec=3)
  >>> isinstance(mock, int)
  True

  __class__ is assignable to, this allows a mock to pass an isinstance() check without forcing you to use a spec:

  >>> mock = Mock()
  >>> mock.__class__ = dict
  >>> isinstance(mock, dict)
  True

class unittest.mock.NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, \*kwargs*)

A non-callable version of Mock. The constructor parameters have the same meaning of Mock, with the exception of return_value and side_effect which have no meaning on a non-callable mock.

Mock objects that use a class or an instance as a spec or spec_set are able to pass isinstance() tests:

>>> mock = Mock(spec=SomeClass)
>>> isinstance(mock, SomeClass)
True
>>> mock = Mock(spec_set=SomeClass())
>>> isinstance(mock, SomeClass)
True

The Mock classes have support for mocking magic methods. See magic methods for the full details.

The mock classes and the patch() decorators all take arbitrary keyword arguments for configuration. For the patch() decorators the keywords are passed to the constructor of the mock being created. The keyword arguments are for configuring attributes of the mock:

>>> m = MagicMock(attribute=3, other='fish')
>>> m.attribute
3
>>> m.other
'fish'

The return value and side effect of child mocks can be set in the same way, using dotted notation. As you can’t use dotted names directly in a call you have to create a dictionary and unpack it using **:

>>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
>>> mock = Mock(some_attribute='eggs', **attrs)
>>> mock.some_attribute
'eggs'
>>> mock.method()
3
>>> mock.other()
Traceback (most recent call last):
  ...
KeyError

A callable mock which was created with a spec (or a spec_set) will introspect the specification object’s signature when matching calls to the mock. Therefore, it can match the actual call’s arguments regardless of whether they were passed positionally or by name:

>>> def f(a, b, c): pass
...
>>> mock = Mock(spec=f)
>>> mock(1, 2, c=3)
<Mock name='mock()' id='140161580456576'>
>>> mock.assert_called_with(1, 2, 3)
>>> mock.assert_called_with(a=1, b=2, c=3)

This applies to assert_called_with(), assert_called_once_with(), assert_has_calls() and assert_any_call(). When Autospeccing, it will also apply to method calls on the mock object.

在 3.4 版更改: Added signature introspection on specced and autospecced mock objects.

class unittest.mock.PropertyMock(\args, **kwargs*)

A mock intended to be used as a property, or other descriptor, on a class. PropertyMock provides __get__() and __set__() methods so you can specify a return value when it is fetched.

Fetching a PropertyMock instance from an object calls the mock, with no args. Setting it calls the mock with the value being set.

>>> class Foo:
...     @property
...     def foo(self):
...         return 'something'
...     @foo.setter
...     def foo(self, value):
...         pass
...
>>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo:
...     mock_foo.return_value = 'mockity-mock'
...     this_foo = Foo()
...     print(this_foo.foo)
...     this_foo.foo = 6
...
mockity-mock
>>> mock_foo.mock_calls
[call(), call(6)]

Because of the way mock attributes are stored you can’t directly attach a PropertyMock to a mock object. Instead you can attach it to the mock type object:

>>> m = MagicMock()
>>> p = PropertyMock(return_value=3)
>>> type(m).foo = p
>>> m.foo
3
>>> p.assert_called_once_with()

class unittest.mock.AsyncMock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, \*kwargs*)

An asynchronous version of MagicMock. The AsyncMock object will behave so the object is recognized as an async function, and the result of a call is an awaitable.

>>> mock = AsyncMock()
>>> asyncio.iscoroutinefunction(mock)
True
>>> inspect.isawaitable(mock())  
True

The result of mock() is an async function which will have the outcome of side_effect or return_value after it has been awaited:

• if side_effect is a function, the async function will return the result of that function,

• if side_effect is an exception, the async function will raise the exception,

• if side_effect is an iterable, the async function will return the next value of the iterable, however, if the sequence of result is exhausted, StopAsyncIteration is raised immediately,

• if side_effect is not defined, the async function will return the value defined by return_value, hence, by default, the async function returns a new AsyncMock object.

Setting the spec of a Mock or MagicMock to an async function will result in a coroutine object being returned after calling.

>>> async def async_func(): pass
...
>>> mock = MagicMock(async_func)
>>> mock
<MagicMock spec='function' id='...'>
>>> mock()  
<coroutine object AsyncMockMixin._mock_call at ...>

Setting the spec of a Mock, MagicMock, or AsyncMock to a class with asynchronous and synchronous functions will automatically detect the synchronous functions and set them as MagicMock (if the parent mock is AsyncMock or MagicMock) or Mock (if the parent mock is Mock). All asynchronous functions will be AsyncMock.

>>> class ExampleClass:
...     def sync_foo():
...         pass
...     async def async_foo():
...         pass
...
>>> a_mock = AsyncMock(ExampleClass)
>>> a_mock.sync_foo
<MagicMock name='mock.sync_foo' id='...'>
>>> a_mock.async_foo
<AsyncMock name='mock.async_foo' id='...'>
>>> mock = Mock(ExampleClass)
>>> mock.sync_foo
<Mock name='mock.sync_foo' id='...'>
>>> mock.async_foo
<AsyncMock name='mock.async_foo' id='...'>

3.8 新版功能.

• assert_awaited()

  Assert that the mock was awaited at least once. Note that this is separate from the object having been called, the await keyword must be used:

  >>> mock = AsyncMock()
  >>> async def main(coroutine_mock):
  ...     await coroutine_mock
  ...
  >>> coroutine_mock = mock()
  >>> mock.called
  True
  >>> mock.assert_awaited()
  Traceback (most recent call last):
  ...
  AssertionError: Expected mock to have been awaited.
  >>> asyncio.run(main(coroutine_mock))
  >>> mock.assert_awaited()

• assert_awaited_once()

  Assert that the mock was awaited exactly once.

  >>> mock = AsyncMock()
  >>> async def main():
  ...     await mock()
  ...
  >>> asyncio.run(main())
  >>> mock.assert_awaited_once()
  >>> asyncio.run(main())
  >>> mock.method.assert_awaited_once()
  Traceback (most recent call last):
  ...
  AssertionError: Expected mock to have been awaited once. Awaited 2 times.

• assert_awaited_with(\args, **kwargs*)

  Assert that the last await was with the specified arguments.

  >>> mock = AsyncMock()
  >>> async def main(*args, **kwargs):
  ...     await mock(*args, **kwargs)
  ...
  >>> asyncio.run(main('foo', bar='bar'))
  >>> mock.assert_awaited_with('foo', bar='bar')
  >>> mock.assert_awaited_with('other')
  Traceback (most recent call last):
  ...
  AssertionError: expected call not found.
  Expected: mock('other')
  Actual: mock('foo', bar='bar')

• assert_awaited_once_with(\args, **kwargs*)

  Assert that the mock was awaited exactly once and with the specified arguments.

  >>> mock = AsyncMock()
  >>> async def main(*args, **kwargs):
  ...     await mock(*args, **kwargs)
  ...
  >>> asyncio.run(main('foo', bar='bar'))
  >>> mock.assert_awaited_once_with('foo', bar='bar')
  >>> asyncio.run(main('foo', bar='bar'))
  >>> mock.assert_awaited_once_with('foo', bar='bar')
  Traceback (most recent call last):
  ...
  AssertionError: Expected mock to have been awaited once. Awaited 2 times.

• assert_any_await(\args, **kwargs*)

  Assert the mock has ever been awaited with the specified arguments.

  >>> mock = AsyncMock()
  >>> async def main(*args, **kwargs):
  ...     await mock(*args, **kwargs)
  ...
  >>> asyncio.run(main('foo', bar='bar'))
  >>> asyncio.run(main('hello'))
  >>> mock.assert_any_await('foo', bar='bar')
  >>> mock.assert_any_await('other')
  Traceback (most recent call last):
  ...
  AssertionError: mock('other') await not found

• assert_has_awaits(calls, any_order=False)

  Assert the mock has been awaited with the specified calls. The await_args_list list is checked for the awaits.

  If any_order is false then the awaits must be sequential. There can be extra calls before or after the specified awaits.

  If any_order is true then the awaits can be in any order, but they must all appear in await_args_list.

  >>> mock = AsyncMock()
  >>> async def main(*args, **kwargs):
  ...     await mock(*args, **kwargs)
  ...
  >>> calls = [call("foo"), call("bar")]
  >>> mock.assert_has_awaits(calls)
  Traceback (most recent call last):
  ...
  AssertionError: Awaits not found.
  Expected: [call('foo'), call('bar')]
  Actual: []
  >>> asyncio.run(main('foo'))
  >>> asyncio.run(main('bar'))
  >>> mock.assert_has_awaits(calls)

• assert_not_awaited()

  Assert that the mock was never awaited.

  >>> mock = AsyncMock()
  >>> mock.assert_not_awaited()

• reset_mock(\args, **kwargs*)

  See Mock.reset_mock(). Also sets await_count to 0, await_args to None, and clears the await_args_list.

• await_count

  An integer keeping track of how many times the mock object has been awaited.

  >>> mock = AsyncMock()
  >>> async def main():
  ...     await mock()
  ...
  >>> asyncio.run(main())
  >>> mock.await_count
  1
  >>> asyncio.run(main())
  >>> mock.await_count
  2

• await_args

  This is either None (if the mock hasn’t been awaited), or the arguments that the mock was last awaited with. Functions the same as Mock.call_args.

  >>> mock = AsyncMock()
  >>> async def main(*args):
  ...     await mock(*args)
  ...
  >>> mock.await_args
  >>> asyncio.run(main('foo'))
  >>> mock.await_args
  call('foo')
  >>> asyncio.run(main('bar'))
  >>> mock.await_args
  call('bar')

• await_args_list

  This is a list of all the awaits made to the mock object in sequence (so the length of the list is the number of times it has been awaited). Before any awaits have been made it is an empty list.

  >>> mock = AsyncMock()
  >>> async def main(*args):
  ...     await mock(*args)
  ...
  >>> mock.await_args_list
  []
  >>> asyncio.run(main('foo'))
  >>> mock.await_args_list
  [call('foo')]
  >>> asyncio.run(main('bar'))
  >>> mock.await_args_list
  [call('foo'), call('bar')]

Calling

Mock objects are callable. The call will return the value set as the return_value attribute. The default return value is a new Mock object; it is created the first time the return value is accessed (either explicitly or by calling the Mock) - but it is stored and the same one returned each time.

Calls made to the object will be recorded in the attributes like call_args and call_args_list.

If side_effect is set then it will be called after the call has been recorded, so if side_effect raises an exception the call is still recorded.

The simplest way to make a mock raise an exception when called is to make side_effect an exception class or instance:

>>> m = MagicMock(side_effect=IndexError)
>>> m(1, 2, 3)
Traceback (most recent call last):
  ...
IndexError
>>> m.mock_calls
[call(1, 2, 3)]
>>> m.side_effect = KeyError('Bang!')
>>> m('two', 'three', 'four')
Traceback (most recent call last):
  ...
KeyError: 'Bang!'
>>> m.mock_calls
[call(1, 2, 3), call('two', 'three', 'four')]

If side_effect is a function then whatever that function returns is what calls to the mock return. The side_effect function is called with the same arguments as the mock. This allows you to vary the return value of the call dynamically, based on the input:

>>> def side_effect(value):
...     return value + 1
...
>>> m = MagicMock(side_effect=side_effect)
>>> m(1)
2
>>> m(2)
3
>>> m.mock_calls
[call(1), call(2)]

If you want the mock to still return the default return value (a new mock), or any set return value, then there are two ways of doing this. Either return mock.return_value from inside side_effect, or return DEFAULT:

>>> m = MagicMock()
>>> def side_effect(*args, **kwargs):
...     return m.return_value
...
>>> m.side_effect = side_effect
>>> m.return_value = 3
>>> m()
3
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> m.side_effect = side_effect
>>> m()
3

To remove a side_effect, and return to the default behaviour, set the side_effect to None:

>>> m = MagicMock(return_value=6)
>>> def side_effect(*args, **kwargs):
...     return 3
...
>>> m.side_effect = side_effect
>>> m()
3
>>> m.side_effect = None
>>> m()
6

The side_effect can also be any iterable object. Repeated calls to the mock will return values from the iterable (until the iterable is exhausted and a StopIteration is raised):

>>> m = MagicMock(side_effect=[1, 2, 3])
>>> m()
1
>>> m()
2
>>> m()
3
>>> m()
Traceback (most recent call last):
  ...
StopIteration

If any members of the iterable are exceptions they will be raised instead of returned:

>>> iterable = (33, ValueError, 66)
>>> m = MagicMock(side_effect=iterable)
>>> m()
33
>>> m()
Traceback (most recent call last):
 ...
ValueError
>>> m()
66

Deleting Attributes

Mock objects create attributes on demand. This allows them to pretend to be objects of any type.

You may want a mock object to return False to a hasattr() call, or raise an AttributeError when an attribute is fetched. You can do this by providing an object as a spec for a mock, but that isn’t always convenient.

You “block” attributes by deleting them. Once deleted, accessing an attribute will raise an AttributeError.

>>> mock = MagicMock()
>>> hasattr(mock, 'm')
True
>>> del mock.m
>>> hasattr(mock, 'm')
False
>>> del mock.f
>>> mock.f
Traceback (most recent call last):
    ...
AttributeError: f

Mock names and the name attribute

Since “name” is an argument to the Mock constructor, if you want your mock object to have a “name” attribute you can’t just pass it in at creation time. There are two alternatives. One option is to use configure_mock():

>>> mock = MagicMock()
>>> mock.configure_mock(name='my_name')
>>> mock.name
'my_name'

A simpler option is to simply set the “name” attribute after mock creation:

>>> mock = MagicMock()
>>> mock.name = "foo"

Attaching Mocks as Attributes

When you attach a mock as an attribute of another mock (or as the return value) it becomes a “child” of that mock. Calls to the child are recorded in the method_calls and mock_calls attributes of the parent. This is useful for configuring child mocks and then attaching them to the parent, or for attaching mocks to a parent that records all calls to the children and allows you to make assertions about the order of calls between mocks:

>>> parent = MagicMock()
>>> child1 = MagicMock(return_value=None)
>>> child2 = MagicMock(return_value=None)
>>> parent.child1 = child1
>>> parent.child2 = child2
>>> child1(1)
>>> child2(2)
>>> parent.mock_calls
[call.child1(1), call.child2(2)]

The exception to this is if the mock has a name. This allows you to prevent the “parenting” if for some reason you don’t want it to happen.

>>> mock = MagicMock()
>>> not_a_child = MagicMock(name='not-a-child')
>>> mock.attribute = not_a_child
>>> mock.attribute()
<MagicMock name='not-a-child()' id='...'>
>>> mock.mock_calls
[]

Mocks created for you by patch() are automatically given names. To attach mocks that have names to a parent you use the attach_mock() method:

>>> thing1 = object()
>>> thing2 = object()
>>> parent = MagicMock()
>>> with patch('__main__.thing1', return_value=None) as child1:
...     with patch('__main__.thing2', return_value=None) as child2:
...         parent.attach_mock(child1, 'child1')
...         parent.attach_mock(child2, 'child2')
...         child1('one')
...         child2('two')
...
>>> parent.mock_calls
[call.child1('one'), call.child2('two')]

1

The only exceptions are magic methods and attributes (those that have leading and trailing double underscores). Mock doesn’t create these but instead raises an AttributeError. This is because the interpreter will often implicitly request these methods, and gets very confused to get a new Mock object when it expects a magic method. If you need magic method support see magic methods.

The patchers

The patch decorators are used for patching objects only within the scope of the function they decorate. They automatically handle the unpatching for you, even if exceptions are raised. All of these functions can also be used in with statements or as class decorators.

patch

注解

The key is to do the patching in the right namespace. See the section where to patch.

unittest.mock.patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, \*kwargs*)

patch() acts as a function decorator, class decorator or a context manager. Inside the body of the function or with statement, the target is patched with a new object. When the function/with statement exits the patch is undone.

If new is omitted, then the target is replaced with an AsyncMock if the patched object is an async function or a MagicMock otherwise. If patch() is used as a decorator and new is omitted, the created mock is passed in as an extra argument to the decorated function. If patch() is used as a context manager the created mock is returned by the context manager.

target should be a string in the form 'package.module.ClassName'. The target is imported and the specified object replaced with the new object, so the target must be importable from the environment you are calling patch() from. The target is imported when the decorated function is executed, not at decoration time.

The spec and spec_set keyword arguments are passed to the MagicMock if patch is creating one for you.

In addition you can pass spec=True or spec_set=True, which causes patch to pass in the object being mocked as the spec/spec_set object.

new_callable allows you to specify a different class, or callable object, that will be called to create the new object. By default AsyncMock is used for async functions and MagicMock for the rest.

A more powerful form of spec is autospec. If you set autospec=True then the mock will be created with a spec from the object being replaced. All attributes of the mock will also have the spec of the corresponding attribute of the object being replaced. Methods and functions being mocked will have their arguments checked and will raise a TypeError if they are called with the wrong signature. For mocks replacing a class, their return value (the ‘instance’) will have the same spec as the class. See the create_autospec() function and Autospeccing.

Instead of autospec=True you can pass autospec=some_object to use an arbitrary object as the spec instead of the one being replaced.

By default patch() will fail to replace attributes that don’t exist. If you pass in create=True, and the attribute doesn’t exist, patch will create the attribute for you when the patched function is called, and delete it again after the patched function has exited. This is useful for writing tests against attributes that your production code creates at runtime. It is off by default because it can be dangerous. With it switched on you can write passing tests against APIs that don’t actually exist!

注解

在 3.5 版更改: If you are patching builtins in a module then you don’t need to pass create=True, it will be added by default.

Patch can be used as a TestCase class decorator. It works by decorating each test method in the class. This reduces the boilerplate code when your test methods share a common patchings set. patch() finds tests by looking for method names that start with patch.TEST_PREFIX. By default this is 'test', which matches the way unittest finds tests. You can specify an alternative prefix by setting patch.TEST_PREFIX.

Patch can be used as a context manager, with the with statement. Here the patching applies to the indented block after the with statement. If you use “as” then the patched object will be bound to the name after the “as”; very useful if patch() is creating a mock object for you.

patch() takes arbitrary keyword arguments. These will be passed to AsyncMock if the patched object is asynchronous, to MagicMock otherwise or to new_callable if specified.

patch.dict(...), patch.multiple(...) and patch.object(...) are available for alternate use-cases.

patch() as function decorator, creating the mock for you and passing it into the decorated function:

>>> @patch('__main__.SomeClass')
... def function(normal_argument, mock_class):
...     print(mock_class is SomeClass)
...
>>> function(None)
True

Patching a class replaces the class with a MagicMock instance. If the class is instantiated in the code under test then it will be the return_value of the mock that will be used.

If the class is instantiated multiple times you could use side_effect to return a new mock each time. Alternatively you can set the return_value to be anything you want.

To configure return values on methods of instances on the patched class you must do this on the return_value. For example:

>>> class Class:
...     def method(self):
...         pass
...
>>> with patch('__main__.Class') as MockClass:
...     instance = MockClass.return_value
...     instance.method.return_value = 'foo'
...     assert Class() is instance
...     assert Class().method() == 'foo'
...

If you use spec or spec_set and patch() is replacing a class, then the return value of the created mock will have the same spec.

>>> Original = Class
>>> patcher = patch('__main__.Class', spec=True)
>>> MockClass = patcher.start()
>>> instance = MockClass()
>>> assert isinstance(instance, Original)
>>> patcher.stop()

The new_callable argument is useful where you want to use an alternative class to the default MagicMock for the created mock. For example, if you wanted a NonCallableMock to be used:

>>> thing = object()
>>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing:
...     assert thing is mock_thing
...     thing()
...
Traceback (most recent call last):
  ...
TypeError: 'NonCallableMock' object is not callable

Another use case might be to replace an object with an io.StringIO instance:

>>> from io import StringIO
>>> def foo():
...     print('Something')
...
>>> @patch('sys.stdout', new_callable=StringIO)
... def test(mock_stdout):
...     foo()
...     assert mock_stdout.getvalue() == 'Something\n'
...
>>> test()

When patch() is creating a mock for you, it is common that the first thing you need to do is to configure the mock. Some of that configuration can be done in the call to patch. Any arbitrary keywords you pass into the call will be used to set attributes on the created mock:

>>> patcher = patch('__main__.thing', first='one', second='two')
>>> mock_thing = patcher.start()
>>> mock_thing.first
'one'
>>> mock_thing.second
'two'

As well as attributes on the created mock attributes, like the return_value and side_effect, of child mocks can also be configured. These aren’t syntactically valid to pass in directly as keyword arguments, but a dictionary with these as keys can still be expanded into a patch() call using **:

>>> config = {'method.return_value': 3, 'other.side_effect': KeyError}
>>> patcher = patch('__main__.thing', **config)
>>> mock_thing = patcher.start()
>>> mock_thing.method()
3
>>> mock_thing.other()
Traceback (most recent call last):
  ...
KeyError

By default, attempting to patch a function in a module (or a method or an attribute in a class) that does not exist will fail with AttributeError:

>>> @patch('sys.non_existing_attribute', 42)
... def test():
...     assert sys.non_existing_attribute == 42
...
>>> test()
Traceback (most recent call last):
  ...
AttributeError: <module 'sys' (built-in)> does not have the attribute 'non_existing'

but adding create=True in the call to patch() will make the previous example work as expected:

>>> @patch('sys.non_existing_attribute', 42, create=True)
... def test(mock_stdout):
...     assert sys.non_existing_attribute == 42
...
>>> test()

在 3.8 版更改: patch() now returns an AsyncMock if the target is an async function.

patch.object

patch.object(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, \*kwargs*)

patch the named member (attribute) on an object (target) with a mock object.

patch.object() can be used as a decorator, class decorator or a context manager. Arguments new, spec, create, spec_set, autospec and new_callable have the same meaning as for patch(). Like patch(), patch.object() takes arbitrary keyword arguments for configuring the mock object it creates.

When used as a class decorator patch.object() honours patch.TEST_PREFIX for choosing which methods to wrap.

You can either call patch.object() with three arguments or two arguments. The three argument form takes the object to be patched, the attribute name and the object to replace the attribute with.

When calling with the two argument form you omit the replacement object, and a mock is created for you and passed in as an extra argument to the decorated function:

>>> @patch.object(SomeClass, 'class_method')
... def test(mock_method):
...     SomeClass.class_method(3)
...     mock_method.assert_called_with(3)
...
>>> test()

spec, create and the other arguments to patch.object() have the same meaning as they do for patch().

patch.dict

patch.dict(in_dict, values=(), clear=False, \*kwargs*)

Patch a dictionary, or dictionary like object, and restore the dictionary to its original state after the test.

in_dict can be a dictionary or a mapping like container. If it is a mapping then it must at least support getting, setting and deleting items plus iterating over keys.

in_dict can also be a string specifying the name of the dictionary, which will then be fetched by importing it.

values can be a dictionary of values to set in the dictionary. values can also be an iterable of (key, value) pairs.

If clear is true then the dictionary will be cleared before the new values are set.

patch.dict() can also be called with arbitrary keyword arguments to set values in the dictionary.

在 3.8 版更改: patch.dict() now returns the patched dictionary when used as a context manager.

patch.dict() can be used as a context manager, decorator or class decorator:

>>> foo = {}
>>> @patch.dict(foo, {'newkey': 'newvalue'})
... def test():
...     assert foo == {'newkey': 'newvalue'}
>>> test()
>>> assert foo == {}

When used as a class decorator patch.dict() honours patch.TEST_PREFIX (default to 'test') for choosing which methods to wrap:

>>> import os
>>> import unittest
>>> from unittest.mock import patch
>>> @patch.dict('os.environ', {'newkey': 'newvalue'})
... class TestSample(unittest.TestCase):
...     def test_sample(self):
...         self.assertEqual(os.environ['newkey'], 'newvalue')

If you want to use a different prefix for your test, you can inform the patchers of the different prefix by setting patch.TEST_PREFIX. For more details about how to change the value of see TEST_PREFIX.

patch.dict() can be used to add members to a dictionary, or simply let a test change a dictionary, and ensure the dictionary is restored when the test ends.

>>> foo = {}
>>> with patch.dict(foo, {'newkey': 'newvalue'}) as patched_foo:
...     assert foo == {'newkey': 'newvalue'}
...     assert patched_foo == {'newkey': 'newvalue'}
...     # You can add, update or delete keys of foo (or patched_foo, it's the same dict)
...     patched_foo['spam'] = 'eggs'
...
>>> assert foo == {}
>>> assert patched_foo == {}

>>> import os
>>> with patch.dict('os.environ', {'newkey': 'newvalue'}):
...     print(os.environ['newkey'])
...
newvalue
>>> assert 'newkey' not in os.environ

Keywords can be used in the patch.dict() call to set values in the dictionary:

>>> mymodule = MagicMock()
>>> mymodule.function.return_value = 'fish'
>>> with patch.dict('sys.modules', mymodule=mymodule):
...     import mymodule
...     mymodule.function('some', 'args')
...
'fish'

patch.dict() can be used with dictionary like objects that aren’t actually dictionaries. At the very minimum they must support item getting, setting, deleting and either iteration or membership test. This corresponds to the magic methods __getitem__(), __setitem__(), __delitem__() and either __iter__() or __contains__().

>>> class Container:
...     def __init__(self):
...         self.values = {}
...     def __getitem__(self, name):
...         return self.values[name]
...     def __setitem__(self, name, value):
...         self.values[name] = value
...     def __delitem__(self, name):
...         del self.values[name]
...     def __iter__(self):
...         return iter(self.values)
...
>>> thing = Container()
>>> thing['one'] = 1
>>> with patch.dict(thing, one=2, two=3):
...     assert thing['one'] == 2
...     assert thing['two'] == 3
...
>>> assert thing['one'] == 1
>>> assert list(thing) == ['one']

patch.multiple

patch.multiple(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, \*kwargs*)

Perform multiple patches in a single call. It takes the object to be patched (either as an object or a string to fetch the object by importing) and keyword arguments for the patches:

with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'):
    ...

Use DEFAULT as the value if you want patch.multiple() to create mocks for you. In this case the created mocks are passed into a decorated function by keyword, and a dictionary is returned when patch.multiple() is used as a context manager.

patch.multiple() can be used as a decorator, class decorator or a context manager. The arguments spec, spec_set, create, autospec and new_callable have the same meaning as for patch(). These arguments will be applied to all patches done by patch.multiple().

When used as a class decorator patch.multiple() honours patch.TEST_PREFIX for choosing which methods to wrap.

If you want patch.multiple() to create mocks for you, then you can use DEFAULT as the value. If you use patch.multiple() as a decorator then the created mocks are passed into the decorated function by keyword.

>>> thing = object()
>>> other = object()
>>> @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
... def test_function(thing, other):
...     assert isinstance(thing, MagicMock)
...     assert isinstance(other, MagicMock)
...
>>> test_function()

patch.multiple() can be nested with other patch decorators, but put arguments passed by keyword after any of the standard arguments created by patch():

>>> @patch('sys.exit')
... @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
... def test_function(mock_exit, other, thing):
...     assert 'other' in repr(other)
...     assert 'thing' in repr(thing)
...     assert 'exit' in repr(mock_exit)
...
>>> test_function()

If patch.multiple() is used as a context manager, the value returned by the context manager is a dictionary where created mocks are keyed by name:

>>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values:
...     assert 'other' in repr(values['other'])
...     assert 'thing' in repr(values['thing'])
...     assert values['thing'] is thing
...     assert values['other'] is other
...

patch methods: start and stop

All the patchers have start() and stop() methods. These make it simpler to do patching in setUp methods or where you want to do multiple patches without nesting decorators or with statements.

To use them call patch(), patch.object() or patch.dict() as normal and keep a reference to the returned patcher object. You can then call start() to put the patch in place and stop() to undo it.

If you are using patch() to create a mock for you then it will be returned by the call to patcher.start.

>>> patcher = patch('package.module.ClassName')
>>> from package import module
>>> original = module.ClassName
>>> new_mock = patcher.start()
>>> assert module.ClassName is not original
>>> assert module.ClassName is new_mock
>>> patcher.stop()
>>> assert module.ClassName is original
>>> assert module.ClassName is not new_mock

A typical use case for this might be for doing multiple patches in the setUp method of a TestCase:

>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         self.patcher1 = patch('package.module.Class1')
...         self.patcher2 = patch('package.module.Class2')
...         self.MockClass1 = self.patcher1.start()
...         self.MockClass2 = self.patcher2.start()
...
...     def tearDown(self):
...         self.patcher1.stop()
...         self.patcher2.stop()
...
...     def test_something(self):
...         assert package.module.Class1 is self.MockClass1
...         assert package.module.Class2 is self.MockClass2
...
>>> MyTest('test_something').run()

警告

If you use this technique you must ensure that the patching is “undone” by calling stop. This can be fiddlier than you might think, because if an exception is raised in the setUp then tearDown is not called. unittest.TestCase.addCleanup() makes this easier:

>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         patcher = patch('package.module.Class')
...         self.MockClass = patcher.start()
...         self.addCleanup(patcher.stop)
...
...     def test_something(self):
...         assert package.module.Class is self.MockClass
...

As an added bonus you no longer need to keep a reference to the patcher object.

It is also possible to stop all patches which have been started by using patch.stopall().

patch.stopall()

Stop all active patches. Only stops patches started with start.

patch builtins

You can patch any builtins within a module. The following example patches builtin ord():

>>> @patch('__main__.ord')
... def test(mock_ord):
...     mock_ord.return_value = 101
...     print(ord('c'))
...
>>> test()
101

TEST_PREFIX

All of the patchers can be used as class decorators. When used in this way they wrap every test method on the class. The patchers recognise methods that start with 'test' as being test methods. This is the same way that the unittest.TestLoader finds test methods by default.

It is possible that you want to use a different prefix for your tests. You can inform the patchers of the different prefix by setting patch.TEST_PREFIX:

>>> patch.TEST_PREFIX = 'foo'
>>> value = 3
>>>
>>> @patch('__main__.value', 'not three')
... class Thing:
...     def foo_one(self):
...         print(value)
...     def foo_two(self):
...         print(value)
...
>>>
>>> Thing().foo_one()
not three
>>> Thing().foo_two()
not three
>>> value
3