unittest.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 позволяет выполнять побочные эффекты, включая создание исключения при вызове 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 есть много других способов настроить его и управлять его поведением. Например, аргумент spec настраивает mock на получение спецификации из другого объекта. Попытка получить доступ к атрибутам или методам в макете, которых нет в спецификации, завершится ошибкой с AttributeError.

Контекстный менеджер patch() decorator позволяет легко имитировать классы или объекты в тестируемом модуле. Указанный вами объект будет заменен на макет (или другой объект) во время тестирования и восстановлен после завершения теста:

>>> 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() может использоваться в качестве контекстного менеджера в операторе 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 magic methods. Проще всего использовать магические методы с помощью класса MagicMock. Он позволяет выполнять такие действия, как:

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

Mock позволяет вам назначать функции (или другие макетные экземпляры) магическим методам, и они будут вызываться соответствующим образом. Класс MagicMock - это просто макетный вариант, в котором все магические методы предварительно созданы для вас (ну, во всяком случае, все полезные).

Ниже приведен пример использования магических методов с обычным макетным классом:

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

Чтобы убедиться, что фиктивные объекты в ваших тестах имеют тот же api, что и объекты, которые они заменяют, вы можете использовать auto-speccing. Автоматическое определение может быть выполнено с помощью аргумента autospec для patch или функции create_autospec(). Автоматическое определение создает фиктивные объекты, которые имеют те же атрибуты и методы, что и объекты, которые они заменяют, и любые функции и методы (включая конструкторы) имеют ту же сигнатуру вызова, что и реальный объект.

Это гарантирует, что ваши макеты завершатся ошибкой так же, как и ваш рабочий код, если они будут использованы неправильно:

>>> 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 - это гибкий макетный объект, предназначенный для замены использования заглушек и тестовых двойников в вашем коде. Макеты могут вызываться и создавать атрибуты в качестве новых макетов при обращении к ним [1]. Обращение к одному и тому же атрибуту всегда возвращает один и тот же макет. Макеты записывают, как вы их используете, что позволяет вам делать выводы о том, что с ними сделал ваш код.

MagicMock является подклассом Mock со всеми магическими методами, предварительно созданными и готовыми к использованию. Существуют также не вызываемые варианты, полезные, когда вы имитируете объекты, которые не являются вызываемыми: NonCallableMock и NonCallableMagicMock

С помощью patch() декораторов можно легко временно заменить классы в определенном модуле на Mock объект. По умолчанию patch() создаст для вас MagicMock. Вы можете указать альтернативный класс Mock, используя аргумент new_callable для patch().

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

Создайте новый объект Mock. Mock принимает несколько необязательных аргументов, которые определяют поведение фиктивного объекта:

• спецификация: Это может быть либо список строк, либо существующий объект (класс или экземпляр), который действует как спецификация для фиктивного объекта. Если вы передаете объект, то при вызове dir для объекта формируется список строк (исключая неподдерживаемые магические атрибуты и методы). При обращении к любому атрибуту, отсутствующему в этом списке, будет выдан AttributeError.

  Если spec является объектом (а не списком строк), то __class__ возвращает класс объекта spec. Это позволяет макетам проходить isinstance() тесты.

• spec_set: более строгий вариант spec. Если он используется, попытка установить или получить атрибут в макете, которого нет в объекте, переданном как spec_set, приведет к появлению AttributeError.

• side_effect: Функция, которая вызывается при каждом вызове Mock. Смотрите атрибут side_effect. Полезен для создания исключений или динамического изменения возвращаемых значений. Функция вызывается с теми же аргументами, что и mock, и если она не возвращает DEFAULT, то в качестве возвращаемого значения используется возвращаемое значение этой функции.

  В качестве альтернативы side_effect может быть классом или экземпляром исключения. В этом случае исключение будет вызвано при вызове mock.

  Если side_effect является итерируемым, то каждый вызов mock будет возвращать следующее значение из итерируемого значения.

  Побочный эффект можно устранить, установив для него значение None.

• return_value: Значение, возвращаемое при вызове mock. По умолчанию это новый Mock (созданный при первом доступе). Смотрите атрибут return_value.

• небезопасно: По умолчанию при обращении к любому атрибуту, имя которого начинается с assert, assret, asert, aseert или assrt, будет выдаваться значение AttributeError. Передача unsafe=True позволит получить доступ к этим атрибутам.

  Добавлено в версии 3.5.

• wraps: элемент, который нужно обернуть для макетного объекта. Если значение wraps не равно None, то при вызове макета вызов будет передан обернутому объекту (возвращая реальный результат). Доступ к атрибуту в макете вернет макетный объект, который обертывает соответствующий атрибут обернутого объекта (поэтому попытка доступа к несуществующему атрибуту приведет к появлению AttributeError).

  Если в макете явно задано значение return_value, то вызовы не передаются в обернутый объект, а вместо этого возвращается значение return_value.

• имя: Если у макета есть имя, то оно будет использовано при повторном использовании макета. Это может быть полезно для отладки. Имя передается дочерним макетам.

Mocks также можно вызывать с произвольными ключевыми аргументами. Они будут использоваться для установки атрибутов в 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)¶

Утверждаем, что макет был вызван ровно один раз и этот вызов был с указанными аргументами.

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

подтвердите, что макет был вызван с указанными аргументами.

Утверждение проходит, если mock когда-либо вызывался, в отличие от assert_called_with() и assert_called_once_with(), которые проходят только в том случае, если вызов является самым последним, а в случае assert_called_once_with() это также должен быть единственный вызов.

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

подтвердите, что макет был вызван указанными вызовами. Список mock_calls проверен на наличие вызовов.

Если значение any_order равно false, то вызовы должны быть последовательными. До или после указанных вызовов могут быть дополнительные вызовы.

Если значение any_order равно true, то вызовы могут быть в любом порядке, но все они должны отображаться в 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()¶

Утверждаю, что макет никогда не вызывался.

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

Метод reset_mock сбрасывает все атрибуты вызова для фиктивного объекта:

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

Изменено в версии 3.6: Добавлены два аргумента только для ключевых слов в функцию reset_mock.

Это может быть полезно, если вы хотите создать серию утверждений, которые повторно используют один и тот же объект. Обратите внимание, что reset_mock() не очищает возвращаемое значение, :attr:`side_effect` или любые дочерние атрибуты, которые вы установили с помощью обычного присваивания по умолчанию. Если вы хотите сбросить значение *return_value или side_effect, то передайте соответствующий параметр как True. Дочерние макеты и макет возвращаемого значения (если таковые имеются) также сбрасываются.

Примечание

return_value и side_effect являются аргументами только для ключевых слов.

mock_add_spec(spec, spec_set=False)¶

Добавьте спецификацию в макет. spec может быть как объектом, так и списком строк. Только атрибуты в spec могут быть извлечены в качестве атрибутов из макета.

Если значение spec_set равно true, то могут быть установлены только атрибуты из спецификации.

attach_mock(mock, attribute)¶

Прикрепите макет в качестве атрибута к этому макету, заменив его имя и родительский элемент. Обращения к прикрепленному макету будут записаны в атрибутах method_calls и mock_calls этого макета.

configure_mock(**kwargs)¶

Задайте атрибуты в макете с помощью аргументов ключевого слова.

Атрибуты, а также возвращаемые значения и побочные эффекты могут быть установлены для дочерних макетов с использованием стандартной точечной нотации и распаковки словаря при вызове метода:

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

То же самое может быть достигнуто при вызове конструктора для 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() существует для упрощения настройки после создания макета.

__dir__()¶

Mock объекты ограничивают результаты dir(some_mock) полезными результатами. Для макетов с спецификацией это включает все разрешенные атрибуты для макета.

Смотрите FILTER_DIR, чтобы узнать, что делает эта фильтрация и как ее отключить.

_get_child_mock(**kw)¶

Создайте дочерние макеты для атрибутов и возвращаемого значения. По умолчанию дочерние макеты будут того же типа, что и родительские. Подклассы Mock могут захотеть переопределить это, чтобы настроить способ создания дочерних макетов.

Для не вызываемых макетов будет использоваться вызываемый вариант (а не какой-либо пользовательский подкласс).

called¶

Логическое значение, представляющее, был ли вызван фиктивный объект или нет:

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

call_count¶

Целое число, сообщающее вам, сколько раз был вызван фиктивный объект:

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

return_value¶

Установите это значение, чтобы настроить значение, возвращаемое при вызове макета:

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

Возвращаемое значение по умолчанию - это фиктивный объект, и вы можете настроить его обычным способом:

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

return_value также может быть задан в конструкторе:

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

side_effect¶

Это может быть либо функция, вызываемая при вызове mock, либо итерируемая функция, либо вызываемое исключение (класс или экземпляр).

Если вы передадите функцию, она будет вызвана с теми же аргументами, что и mock, и если функция не вернет синглтон DEFAULT, вызов mock вернет все, что возвращает функция. Если функция возвращает DEFAULT, то макет вернет свое обычное значение (из return_value).

Если вы передаете iterable, он используется для извлечения итератора, который должен выдавать значение при каждом вызове. Это значение может быть либо экземпляром исключения, который должен быть вызван, либо значением, которое должно быть возвращено из вызова mock (обработка DEFAULT идентична функции case).

Пример макета, который вызывает исключение (для тестирования обработки исключений API):

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

Использование side_effect для возврата последовательности значений:

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

Использование вызываемого:

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

side_effect может быть задано в конструкторе. Вот пример, который добавляет единицу к значению, с которым вызывается mock, и возвращает его:

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

Установка side_effect на None очищает его:

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

call_args¶

Это либо None (если макет не был вызван), либо аргументы, с которыми макет вызывался в последний раз. Это будет в виде кортежа: первый элемент, к которому также можно получить доступ через свойство args, - это любые упорядоченные аргументы, с которыми был вызван mock (или пустой кортеж), и второй элемент, к которому также можно получить доступ через kwargs свойство - это любые аргументы ключевого слова (или пустой словарь).

>>> 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, а также элементы списков call_args_list, method_calls и mock_calls являются объектами call. Это кортежи, поэтому их можно распаковать, чтобы получить доступ к отдельным аргументам и составить более сложные утверждения. Смотрите calls as tuples.

Изменено в версии 3.8: Добавлены свойства args и kwargs.

call_args_list¶

Это список всех последовательных обращений к фиктивному объекту (таким образом, длина списка равна количеству обращений к нему). До того, как были сделаны какие-либо обращения, этот список был пустым. Объект call может быть использован для удобного построения списков вызовов для сравнения с 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

Элементы call_args_list являются объектами call. Их можно распаковать в виде кортежей, чтобы получить доступ к отдельным аргументам. Смотрите calls as tuples.

method_calls¶

Помимо отслеживания обращений к самим себе, mocks также отслеживают обращения к методам и атрибутам, а также к их методам и атрибутам:

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

Элементы method_calls являются объектами call. Их можно распаковать в виде кортежей, чтобы получить доступ к отдельным аргументам. Смотрите calls as tuples.

mock_calls¶

mock_calls записывает все вызовы макетного объекта, его методы, магические методы * и* макеты возвращаемых значений.

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

Элементы mock_calls являются объектами call. Их можно распаковать в виде кортежей, чтобы получить доступ к отдельным аргументам. Смотрите calls as tuples.

Примечание

Способ записи mock_calls означает, что при выполнении вложенных вызовов параметры вызовов-предков не записываются и поэтому всегда будут сравниваться равными:

>>> 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__¶

Обычно атрибут __class__ объекта возвращает его тип. Для фиктивного объекта с символом spec, __class__ вместо этого возвращает класс спецификации. Это позволяет фиктивным объектам проходить isinstance() тесты для объекта, который они заменяют, маскируясь под:

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

__class__ присваивается, это позволяет макету передавать проверку isinstance(), не заставляя вас использовать спецификацию:

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

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

Не вызываемая версия Mock. Параметры конструктора имеют то же значение, что и Mock, за исключением return_value и side_effect, которые не имеют значения в не вызываемом макете.

Имитационные объекты, использующие класс или экземпляр в качестве spec или spec_set, могут проходить isinstance() тесты:

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

Классы Mock поддерживают имитацию магических методов. Более подробную информацию смотрите в magic methods.

Классы mock и декораторы patch() принимают произвольные аргументы ключевого слова для настройки. Для декораторов patch() ключевые слова передаются в конструктор создаваемого макета. Аргументы ключевого слова предназначены для настройки атрибутов макета:

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

Возвращаемое значение и побочный эффект дочерних макетов можно задать таким же образом, используя точечную запись. Поскольку вы не можете использовать точечные имена непосредственно в вызове, вам нужно создать словарь и распаковать его, используя **:

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

Вызываемый макет, созданный с помощью spec (или spec_set), будет анализировать сигнатуру объекта спецификации при сопоставлении вызовов с макетом. Таким образом, он может соответствовать фактическим аргументам вызова независимо от того, были ли они переданы позиционно или по имени:

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

Это относится к assert_called_with(), assert_called_once_with(), assert_has_calls() и assert_any_call(). Когда Автоматическая настройка, это также будет применяться к вызовам методов для фиктивного объекта.

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

Макет, предназначенный для использования в качестве property или другого descriptor в классе. PropertyMock предоставляет методы __get__() и __set__(), чтобы вы могли указать возвращаемое значение значение при его извлечении.

Выборка экземпляра PropertyMock из объекта вызывает mock без аргументов. Установка вызывает mock с установленным значением.

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

Из-за способа хранения фиктивных атрибутов вы не можете напрямую прикрепить PropertyMock к фиктивному объекту. Вместо этого вы можете прикрепить его к объекту фиктивного типа:

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

Асинхронная версия MagicMock. Объект AsyncMock будет вести себя таким образом, что объект распознается как асинхронная функция, а результатом вызова является ожидаемая функция.

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

Результатом mock() является асинхронная функция, которая будет иметь результат side_effect или return_value после того, как он будет ожидаться:

• если side_effect является функцией, то асинхронная функция вернет результат этой функции,

• если side_effect является исключением, асинхронная функция вызовет это исключение,

• если side_effect является итерируемым, асинхронная функция вернет следующее значение итерируемого значения, однако, если последовательность результатов исчерпана, StopAsyncIteration вызывается немедленно,

• если side_effect не определено, асинхронная функция вернет значение, определенное с помощью return_value, следовательно, по умолчанию асинхронная функция возвращает новый объект AsyncMock.

Установка spec для Mock или MagicMock асинхронной функции приведет к тому, что после вызова будет возвращен объект сопрограммы.

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

Установка spec для класса с асинхронными и синхронными функциями Mock, MagicMock, или AsyncMock автоматически определит синхронные функции и установит для них значение MagicMock (если родительский класс имеет асинхронные и синхронные функции). макет равен AsyncMock или MagicMock) или Mock (если родительский макет равен Mock). Все асинхронные функции будут иметь значение 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()¶

Подтвердите, что макет ожидался по крайней мере один раз. Обратите внимание, что это не связано с вызовом объекта, поэтому необходимо использовать ключевое слово await:

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

Утверждаем, что макет ожидался ровно один раз.

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

Подтвердите, что последнее ожидание было выполнено с указанными аргументами.

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

Утверждают, что макет ожидался ровно один раз и с указанными аргументами.

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

Утверждайте, что макет когда-либо ожидался с указанными аргументами.

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

Подтвердите, что макет ожидался с помощью указанных вызовов. Список await_args_list проверяется на наличие ожидаемых вызовов.

Если значение any_order равно false, то ожидания должны быть последовательными. Могут быть дополнительные вызовы до или после указанного ожидания.

Если значение any_order равно true, то ожидания могут быть в любом порядке, но все они должны отображаться в 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()¶

Утверждаю, что розыгрыша никто и не ждал.

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

reset_mock(*args, **kwargs)¶

Смотрите Mock.reset_mock(). Также для await_count устанавливается значение 0, для await_args - значение Нет, а для await_args_list значение очищается.

await_count¶

Целое число, отслеживающее, сколько раз ожидался макетный объект.

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

await_args¶

Это либо None (если макет не ожидался), либо аргументы, с которыми макет ожидался в последний раз. Работает так же, как 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¶

Это список всех ожидаемых действий, выполненных для фиктивного объекта в определенной последовательности (таким образом, длина списка равна количеству раз, когда он ожидался). До того, как были выполнены какие-либо ожидания, этот список пуст.

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

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

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

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

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

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

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

>>> 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 = MagicMock()
>>> mock.configure_mock(name='my_name')
>>> mock.name
'my_name'

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

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

>>> 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
[]

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

Исправители¶

Средства оформления исправлений используются для исправления объектов только в рамках функции, которую они оформляют. Они автоматически выполняют удаление исправлений, даже если возникают исключения. Все эти функции также могут использоваться в операторах with или как средства оформления классов.

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

>>> 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'
...

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

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

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

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

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

>>> @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_attribute'

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

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

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

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

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

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

>>> 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']

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

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

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

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

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

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

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

>>> @patch.object(SomeClass, 'class_method')
... @patch.object(SomeClass, 'static_method')
... def test(mock1, mock2):
...     assert SomeClass.static_method is mock1
...     assert SomeClass.class_method is mock2
...     SomeClass.static_method('foo')
...     SomeClass.class_method('bar')
...     return mock1, mock2
...
>>> mock1, mock2 = test()
>>> mock1.assert_called_once_with('foo')
>>> mock2.assert_called_once_with('bar')

a.py
    -> Defines SomeClass

b.py
    -> from a import SomeClass
    -> some_function instantiates SomeClass

@patch('b.SomeClass')

@patch('a.SomeClass')

Поддержка MagicMock и магических методов¶

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

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

>>> mock = MagicMock()
>>> mock[3] = 'fish'
>>> mock.__setitem__.assert_called_with(3, 'fish')
>>> mock.__getitem__.return_value = 'result'
>>> mock[2]
'result'

>>> mock = MagicMock()
>>> int(mock)
1
>>> len(mock)
0
>>> list(mock)
[]
>>> object() in mock
False

>>> MagicMock() == 3
False
>>> MagicMock() != 3
True
>>> mock = MagicMock()
>>> mock.__eq__.return_value = True
>>> mock == 3
True

>>> mock = MagicMock()
>>> mock.__iter__.return_value = ['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']

>>> mock.__iter__.return_value = iter(['a', 'b', 'c'])
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
[]

Помощники¶

>>> real = ProductionClass()
>>> real.method = Mock(name="method")
>>> real.method.return_value = sentinel.some_object
>>> result = real.method()
>>> assert result is sentinel.some_object
>>> result
sentinel.some_object

>>> m = MagicMock()
>>> m(1).method(arg='foo').other('bar')(2.0)
<MagicMock name='mock().method().other()()' id='...'>
>>> kall = call(1).method(arg='foo').other('bar')(2.0)
>>> kall.call_list()
[call(1),
 call().method(arg='foo'),
 call().method().other('bar'),
 call().method().other()(2.0)]
>>> m.mock_calls == kall.call_list()
True

>>> m = MagicMock(return_value=None)
>>> m(1, 2, 3, arg='one', arg2='two')
>>> kall = m.call_args
>>> kall.args
(1, 2, 3)
>>> kall.kwargs
{'arg': 'one', 'arg2': 'two'}
>>> kall.args is kall[0]
True
>>> kall.kwargs is kall[1]
True

>>> m = MagicMock()
>>> m.foo(4, 5, 6, arg='two', arg2='three')
<MagicMock name='mock.foo()' id='...'>
>>> kall = m.mock_calls[0]
>>> name, args, kwargs = kall
>>> name
'foo'
>>> args
(4, 5, 6)
>>> kwargs
{'arg': 'two', 'arg2': 'three'}
>>> name is m.mock_calls[0][0]
True

>>> mock = Mock(return_value=None)
>>> mock('foo', bar=object())
>>> mock.assert_called_once_with('foo', bar=ANY)