26.4. unittest.mock – библиотека mock-объектов¶unittest.mock – mock object library

26.4.2.1. Вызов¶Calling

Объекты-макеты вызываемы. Вызов возвращает значение, установленное в атрибуте return_value. По умолчанию возвращаемое значение – новый объект Mock; он создаётся при первом обращении к возвращаемому значению (явном или через вызов макета), но затем сохраняется и возвращается при каждом последующем вызове.

Вызовы объекта будут записаны в таких атрибутах, как call_args и call_args_list.

Если задан side_effect, то он будет вызван после записи вызова; поэтому, если side_effect возбуждает исключение, вызов всё равно будет записан.

Простейший способ заставить макет возбуждать исключение при вызове – сделать side_effect классом или экземпляром исключения:

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

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

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

Если нужно, чтобы макет по-прежнему возвращал значение по умолчанию (новый макет) или любое установленное возвращаемое значение, есть два способа. Либо вернуть mock.return_value изнутри side_effect, либо вернуть 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

Чтобы удалить side_effect и вернуться к поведению по умолчанию, установите side_effect в 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

side_effect также может быть любым итерируемым объектом. При повторных вызовах макета будут возвращаться значения из итерируемого объекта (пока он не исчерпается и не будет возбуждено StopIteration):

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

26.4.2.2. Удаление атрибутов¶Deleting Attributes

Объекты Mock создают атрибуты по запросу. Это позволяет им притворяться объектами любого типа.

Возможно, потребуется, чтобы mock-объект возвращал False на вызов hasattr() или вызывал AttributeError при запросе атрибута. Это можно сделать, передав объект в качестве spec для mock, но это не всегда удобно.

Атрибуты «блокируются» их удалением. После удаления обращение к атрибуту вызовет 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

26.4.2.3. Имена mock'ов и атрибут name¶Mock names and the name attribute

Поскольку «name» – это аргумент конструктора Mock, если требуется, чтобы mock-объект имел атрибут «name», его нельзя просто передать при создании. Есть две альтернативы. Один из вариантов – использовать configure_mock():

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

Более простой вариант – просто установить атрибут «name» после создания макета:

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

26.4.2.4. Прикрепление моков в качестве атрибутов¶Attaching Mocks as Attributes

Когда mock прикрепляется как атрибут другого mock (или как возвращаемое значение), он становится «дочерним» по отношению к этому mock. Вызовы к дочернему объекту записываются в атрибуты method_calls и mock_calls родительского объекта. Это полезно для настройки дочерних mock'ов и последующего их прикрепления к родительскому, или для прикрепления mock'ов к родительскому, который записывает все вызовы к дочерним и позволяет делать утверждения о порядке вызовов между mock'ами:

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

Mock'ы, создаваемые patch(), автоматически получают имена. Чтобы прикрепить именованные mock'и к родительскому, используется метод attach_mock():

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

26.4.3.1. patch¶

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

patch() работает как декоратор функции, декоратор класса или контекстный менеджер. Внутри тела функции или оператора with target заменяется объектом new. При выходе из функции/оператора with патч отменяется.

Если new опущен, то target заменяется на MagicMock. Если patch() используется как декоратор и new опущен, то созданный mock передаётся как дополнительный аргумент декорируемой функции. Если patch() используется как контекстный менеджер, созданный mock возвращается контекстным менеджером.

target должен быть строкой вида 'package.module.ClassName'. target импортируется, и указанный объект заменяется объектом new, поэтому target должен быть импортируемым из окружения, в котором вызывается patch(). target импортируется при выполнении декорированной функции, а не во время декорирования.

Именованные аргументы spec и spec_set передаются в MagicMock, если patch создаёт его.

Кроме того, можно передать spec=True или spec_set=True, что заставит patch передать заменяемый объект в качестве spec/spec_set.

new_callable позволяет указать другой класс или вызываемый объект, который будет вызван для создания объекта new. По умолчанию используется MagicMock.

Более мощной формой spec является autospec. Если установить autospec=True, то mock будет создан со spec от заменяемого объекта. Все атрибуты mock также будут иметь spec соответствующего атрибута заменяемого объекта. Методы и функции, которые заменяются mock, будут проверять свои аргументы и вызывать TypeError при вызове с неверной сигнатурой. Для mock'ов, заменяющих класс, их возвращаемое значение («экземпляр») будет иметь тот же spec, что и класс. См. функцию create_autospec() и раздел Autospeccing.

Вместо autospec=True можно передать autospec=some_object, чтобы использовать произвольный объект в качестве spec вместо заменяемого.

По умолчанию patch() не сможет заменить атрибуты, которые не существуют. Если передать create=True, и атрибут не существует, patch создаст его при вызове патченной функции, а затем снова удалит. Это полезно для написания тестов на атрибуты, которые рабочий код создаёт во время выполнения. По умолчанию эта возможность отключена, так как может быть опасной. С ней можно писать успешные тесты на API, которых на самом деле не существует!

Patch можно использовать как декоратор класса TestCase. Он работает, декорируя каждый тестовый метод в классе. Это уменьшает шаблонный код, когда тестовые методы имеют общий набор патчей. patch() находит тесты, ища методы, имена которых начинаются с patch.TEST_PREFIX. По умолчанию это 'test', что совпадает с тем, как unittest находит тесты. Можно указать альтернативный префикс, установив patch.TEST_PREFIX.

Patch можно использовать как контекстный менеджер с оператором with. В этом случае патчинг применяется к блоку с отступом после оператора with. Если используется «as», то заменённый объект будет привязан к имени после «as»; это очень полезно, если patch() создаёт mock-объект.

patch() принимает произвольные именованные аргументы. Они будут переданы Mock (или new_callable) при создании.

patch.dict(...), patch.multiple(...) и patch.object(...) доступны для других сценариев использования.

patch() в качестве декоратора функции, создающий mock и передающий его в декорированную функцию:

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

Патчинг класса заменяет класс на MagicMock экземпляр. Если класс инстанциируется в тестируемом коде, то будет использоваться return_value mock'а.

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

Чтобы настроить возвращаемые значения методов экземпляров патченного класса, это нужно делать на return_value. Например:

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

Если используется spec или spec_set, и patch() заменяет класс, то возвращаемое значение созданного mock будет иметь тот же spec.

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

Аргумент new_callable полезен, когда требуется использовать альтернативный класс вместо MagicMock для создаваемого mock. Например, если нужно, чтобы использовался NonCallableMock:

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

Ещё один вариант использования – замена объекта экземпляром io.StringIO:

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

Когда patch() создаёт мок, обычно первым делом требуется настроить этот мок. Часть настройки можно выполнить в самом вызове patch. Любые произвольные ключевые слова, переданные в вызов, будут использованы для установки атрибутов созданного мока:

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

Кроме того, можно настроить не только атрибуты созданного мока, но и атрибуты дочерних моков, такие как return_value и side_effect. Их нельзя передать напрямую в качестве ключевых аргументов, но словарь с этими ключами можно развернуть в вызов patch() с помощью **:

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

26.4.3.2. patch.object¶

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

Заменяет именованный член (атрибут) объекта (цель) на мок-объект.

patch.object() можно использовать как декоратор, декоратор класса или контекстный менеджер. Аргументы new, spec, create, spec_set, autospec и new_callable имеют тот же смысл, что и в patch(). Как и patch(), patch.object() принимает произвольные ключевые аргументы для настройки создаваемого объекта-мока.

При использовании в качестве декоратора класса patch.object() учитывает patch.TEST_PREFIX для выбора методов, которые нужно обернуть.

patch.object() можно вызывать как с тремя, так и с двумя аргументами. Форма с тремя аргументами принимает объект для подмены, имя атрибута и объект, на который нужно заменить атрибут.

При вызове с двумя аргументами заменяющий объект опускается, и мок создаётся и передаётся как дополнительный аргумент в декорируемую функцию:

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

spec, create и остальные аргументы patch.object() имеют тот же смысл, что и в patch().

26.4.3.3. patch.dict¶

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

Исправляет словарь или подобный словарю объект и восстанавливает его исходное состояние после завершения теста.

in_dict может быть словарём или контейнером, подобным отображению. Если это отображение, оно должно как минимум поддерживать получение, установку и удаление элементов, а также итерацию по ключам.

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

values может быть словарём значений для установки в словаре. values также может быть итерируемым объектом, содержащим пары (key, value).

Если clear равен true, то словарь будет очищен перед установкой новых значений.

patch.dict() также можно вызывать с произвольными ключевыми аргументами для установки значений в словаре.

patch.dict() можно использовать как контекстный менеджер, декоратор или декоратор класса. При использовании в качестве декоратора класса patch.dict() учитывает patch.TEST_PREFIX для выбора методов, которые нужно обернуть.

patch.dict() можно использовать для добавления элементов в словарь или просто чтобы позволить тесту изменить словарь и гарантировать, что после завершения теста словарь будет восстановлен.

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

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

В вызове patch.dict() можно использовать ключевые слова для установки значений в словаре:

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

patch.dict() можно использовать с объектами, похожими на словарь, которые на самом деле не являются словарями. Минимально они должны поддерживать получение, установку и удаление элементов, а также либо итерацию, либо проверку членства. Это соответствует магическим методам __getitem__(), __setitem__(), __delitem__() и либо __iter__(), либо __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']

26.4.3.4. patch.multiple¶

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

Выполняет несколько патчей за один вызов. Принимает объект для патча (либо сам объект, либо строку для его импорта) и именованные аргументы для патчей:

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

Используйте DEFAULT в качестве значения, если хотите, чтобы patch.multiple() создавал моки за вас. В этом случае созданные моки передаются в декорированную функцию как ключевые аргументы, а при использовании patch.multiple() в качестве контекстного менеджера возвращается словарь.

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

При использовании в качестве декоратора класса patch.multiple() учитывает patch.TEST_PREFIX для выбора методов, которые нужно обернуть.

Если вы хотите, чтобы patch.multiple() создавал моки за вас, вы можете использовать DEFAULT в качестве значения. Если вы используете patch.multiple() как декоратор, то созданные моки передаются в декорированную функцию по ключу.

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

Если patch.multiple() используется как контекстный менеджер, то возвращаемое им значение – это словарь, в котором созданные моки сгруппированы по имени:

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

26.4.3.5. Методы patch: start и stop¶patch methods: start and stop

У всех патчеров есть методы start() и stop(). Они упрощают выполнение подмен в методах setUp или в тех случаях, когда нужно сделать несколько подмен, не вкладывая декораторы или операторы with.

Для их использования вызовите patch(), patch.object() или patch.dict() как обычно и сохраните ссылку на возвращаемый объект patcher. Затем вы можете вызвать start(), чтобы применить подмену, и stop(), чтобы отменить её.

Если вы используете patch() для создания мока, то он будет возвращён вызовом 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

Типичный вариант использования – выполнение нескольких подмен в методе setUp класса TestCase:

>>> class MyTest(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(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.stopall().

patch.stopall()¶

Останавливает все активные патчи. Останавливает только патчи, запущенные с помощью start.

26.4.3.6. TEST_PREFIX¶

Все патчеры можно использовать в качестве декораторов классов. При таком использовании они оборачивают каждый тестовый метод класса. Патчеры распознают методы, которые начинаются с 'test', как тестовые. Это тот же способ, которым unittest.TestLoader по умолчанию находит тестовые методы.

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

26.4.3.7. Вложение декораторов патчей¶Nesting Patch Decorators

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

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

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

Обратите внимание: декораторы применяются снизу вверх. Это стандартный порядок применения декораторов в Python. Порядок созданных заглушек, передаваемых в тестовую функцию, соответствует этому порядку.

26.4.3.8. Где патчить¶Where to patch

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

Основной принцип: патч применяется там, где объект ищется, а это не обязательно то же место, где он определён. Несколько примеров помогут прояснить это.

Представим проект, который нужно протестировать, со следующей структурой:

a.py
    -> Defines SomeClass

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

Теперь мы хотим протестировать some_function, но подменить SomeClass с помощью patch(). Проблема в том, что когда мы импортируем модуль b (а нам придётся это сделать), он импортирует SomeClass из модуля a. Если мы используем patch() для подмены a.SomeClass, то это не повлияет на наш тест; модуль b уже содержит ссылку на настоящий SomeClass, и кажется, что наш патч не сработал.

Ключевой момент – патчить SomeClass там, где он используется (или где происходит его поиск). В данном случае some_function будет искать SomeClass в модуле b, куда мы его импортировали. Патч должен выглядеть так:

@patch('b.SomeClass')

Однако рассмотрим альтернативный сценарий, когда вместо from a import SomeClass модуль b выполняет import a, а some_function использует a.SomeClass. Обе эти формы импорта распространены. В этом случае класс, который мы хотим подменить, ищется в модуле, поэтому мы должны патчить a.SomeClass вместо:

@patch('a.SomeClass')

26.4.3.9. Патчинг дескрипторов и прокси-объектов¶Patching Descriptors and Proxy Objects

И patch, и patch.object корректно заменяют и восстанавливают дескрипторы: методы класса, статические методы и свойства. Заменять их следует на классе, а не на экземпляре. Они также работают с некоторыми объектами, проксирующими доступ к атрибутам, например, объект настроек Django.

26.4.4.1. Подмена магических методов¶Mocking Magic Methods

Mock поддерживает подмену методов протоколов Python, также известных как «магические методы». Это позволяет мок-объектам заменять контейнеры или другие объекты, реализующие протоколы Python.

Поскольку магические методы ищутся иначе, чем обычные методы [2], эта поддержка была реализована специально. Это означает, что поддерживаются только определённые магические методы. Список поддерживаемых методов включает почти все. Если каких-то не хватает, пожалуйста, сообщите.

Магические методы подменяются установкой нужного метода в функцию или экземпляр мока. Если используется функция, она обязана принимать self в качестве первого аргумента [3].

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

Один из вариантов использования – подмена объектов, используемых в качестве контекстных менеджеров в инструкции with:

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

Вызовы магических методов не отображаются в method_calls, но записываются в mock_calls.

Полный список поддерживаемых магических методов:

• __hash__, __sizeof__, __repr__ и __str__
• __dir__, __format__ и __subclasses__
• __floor__, __trunc__ и __ceil__
• Сравнения: __lt__, __gt__, __le__, __ge__, __eq__ и __ne__
• Методы контейнеров: __getitem__, __setitem__, __delitem__, __contains__, __len__, __iter__, __reversed__ и __missing__
• Контекстный менеджер: __enter__ и __exit__
• Унарные числовые методы: __neg__, __pos__ и __invert__
• Числовые методы (включая правосторонние и варианты с присваиванием): __add__, __sub__, __mul__, __div__, __truediv__, __floordiv__, __mod__, __divmod__, __lshift__, __rshift__, __and__, __xor__, __or__ и __pow__
• Методы числового преобразования: __complex__, __int__, __float__ и __index__
• Методы дескрипторов: __get__, __set__ и __delete__
• Сериализация (pickle): __reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, __getstate__ и __setstate__

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

• __getattr__, __setattr__, __init__ и __new__
• __prepare__, __instancecheck__, __subclasscheck__, __del__

26.4.4.2. Magic Mock¶

Есть две разновидности MagicMock: MagicMock и NonCallableMagicMock.

class unittest.mock.MagicMock(*args, **kw)¶

MagicMock – это подкласс Mock с реализациями по умолчанию большинства магических методов. Можно использовать MagicMock, не настраивая магические методы вручную.

Параметры конструктора имеют тот же смысл, что и для Mock.

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

class unittest.mock.NonCallableMagicMock(*args, **kw)¶

Невызываемая версия MagicMock.

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

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

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

По умолчанию многие методы протокола должны возвращать объекты определенного типа. Эти методы предварительно настроены с возвращаемым значением по умолчанию, так что их можно использовать, ничего не делая, если возвращаемое значение не интересует. Вы всё еще можете установить возвращаемое значение вручную, если хотите изменить значение по умолчанию.

Методы и их значения по умолчанию:

• __lt__: NotImplemented
• __gt__: NotImplemented
• __le__: NotImplemented
• __ge__: NotImplemented
• __int__: 1
• __contains__: False
• __len__: 1
• __iter__: iter([])
• __exit__: False
• __complex__: 1j
• __float__: 1.0
• __bool__: True
• __index__: 1
• __hash__: хэш по умолчанию для мока
• __str__: строковое представление по умолчанию для мока
• __sizeof__: размер по умолчанию для мока

Например:

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

Два метода сравнения, __eq__() и __ne__(), являются особыми. Они выполняют сравнение на равенство по умолчанию на основе идентичности, используя атрибут side_effect, если только не изменить возвращаемое значение, чтобы оно возвращало что-то другое:

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

Возвращаемое значение MagicMock.__iter__() может быть любым итерируемым объектом и не обязательно должно быть итератором:

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

У MagicMock настроены все поддерживаемые магические методы, за исключением некоторых устаревших и редко используемых. При желании их можно настроить.

Магические методы, которые поддерживаются, но не настроены по умолчанию в MagicMock:

• __subclasses__
• __dir__
• __format__
• __get__, __set__ и __delete__
• __reversed__ и __missing__
• __reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, __getstate__ и __setstate__
• __getformat__ и __setformat__

26.4.5.1. sentinel¶

unittest.mock.sentinel¶

Объект sentinel предоставляет удобный способ создания уникальных объектов для тестов.

Атрибуты создаются по запросу при обращении к ним по имени. Обращение к одному и тому же атрибуту всегда возвращает один и тот же объект. Возвращаемые объекты имеют понятное строковое представление (repr), чтобы сообщения об ошибках тестов были читаемыми.

Иногда при тестировании нужно проверить, что конкретный объект передаётся в качестве аргумента другому методу или возвращается. Нередко для этого создают именованные sentinel-объекты. sentinel предоставляет удобный способ создания и проверки идентичности таких объектов.

В этом примере мы подменяем (monkey patch) method, чтобы он возвращал sentinel.some_object:

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

26.4.5.2. DEFAULT¶

unittest.mock.DEFAULT¶

Объект DEFAULT – это предварительно созданный sentinel (фактически sentinel.DEFAULT). Он может использоваться функциями side_effect, чтобы указать, что следует использовать обычное возвращаемое значение.

26.4.5.3. call¶

unittest.mock.call(*args, **kwargs)¶

call() – вспомогательный объект для упрощения проверок, сравнения с call_args, call_args_list, mock_calls и method_calls. call() также можно использовать с assert_has_calls().

>>> m = MagicMock(return_value=None)
>>> m(1, 2, a='foo', b='bar')
>>> m()
>>> m.call_args_list == [call(1, 2, a='foo', b='bar'), call()]
True

call.call_list()¶

Для объекта call, представляющего несколько вызовов, call_list() возвращает список всех промежуточных вызовов, а также конечного вызова.

call_list особенно полезен для проверок цепочечных вызовов. Цепочечный вызов – это несколько вызовов в одной строке кода. В результате в mock_calls мока появляется несколько записей. Ручное построение последовательности вызовов может быть утомительным.

call_list() может построить последовательность вызовов из того же цепочечного вызова:

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

Объект call является кортежем из (позиционные аргументы, именованные аргументы) или (имя, позиционные аргументы, именованные аргументы) в зависимости от того, как он был создан. Когда вы создаёте их самостоятельно, это не особенно интересно, но объекты call, находящиеся в атрибутах Mock.call_args, Mock.call_args_list и Mock.mock_calls, можно исследовать, чтобы получить отдельные аргументы, которые они содержат.

Объекты call в Mock.call_args и Mock.call_args_list являются двухэлементными кортежами (позиционные аргументы, именованные аргументы), тогда как объекты call в Mock.mock_calls, а также те, что вы создаёте самостоятельно, – трёхэлементные кортежи (имя, позиционные аргументы, именованные аргументы).

Вы можете использовать их «кортежность», чтобы извлекать отдельные аргументы для более сложной интроспекции и проверок. Позиционные аргументы – это кортеж (пустой кортеж, если позиционных аргументов нет), а именованные аргументы – это словарь:

>>> m = MagicMock(return_value=None)
>>> m(1, 2, 3, arg='one', arg2='two')
>>> kall = m.call_args
>>> args, kwargs = kall
>>> args
(1, 2, 3)
>>> kwargs
{'arg2': 'two', 'arg': 'one'}
>>> args is kall[0]
True
>>> 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
{'arg2': 'three', 'arg': 'two'}
>>> name is m.mock_calls[0][0]
True

26.4.5.4. create_autospec¶

unittest.mock.create_autospec(spec, spec_set=False, instance=False, **kwargs)¶

Создаёт макет-объект, используя другой объект в качестве спецификации. Атрибуты макета будут использовать соответствующий атрибут объекта spec в качестве своей спецификации.

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

Если spec_set равно True, то попытка установить атрибуты, которые не существуют в объекте спецификации, вызовет AttributeError.

Если класс используется в качестве спецификации, то возвращаемое значение мока (экземпляр класса) будет иметь ту же спецификацию. Класс можно использовать как спецификацию для объекта экземпляра, передав instance=True. Возвращаемый мок будет вызываемым, только если экземпляры мока являются вызываемыми.

create_autospec() также принимает произвольные именованные аргументы, которые передаются конструктору создаваемого мока.

Смотрите Autospeccing с примерами использования автоспецификации с create_autospec() и аргумента autospec для patch().

26.4.5.5. ANY¶

unittest.mock.ANY¶

Иногда требуется проверять только некоторые из аргументов в вызове mock, либо не обращать внимания на часть аргументов, либо извлекать их по отдельности из call_args и выполнять более сложные проверки.

Чтобы игнорировать определённые аргументы, можно передавать объекты, которые сравниваются равными чему угодно. Тогда вызовы assert_called_with() и assert_called_once_with() будут успешными независимо от того, что было передано.

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

ANY также можно использовать при сравнении со списками вызовов, такими как mock_calls:

>>> m = MagicMock(return_value=None)
>>> m(1)
>>> m(1, 2)
>>> m(object())
>>> m.mock_calls == [call(1), call(1, 2), ANY]
True

26.4.5.6. FILTER_DIR¶

unittest.mock.FILTER_DIR¶

FILTER_DIR – это переменная уровня модуля, управляющая тем, как объекты mock реагируют на dir() (только для Python 2.6 и новее). Значение по умолчанию – True, которое использует фильтрацию, описанную ниже, чтобы показывать только полезные члены. Если такая фильтрация не устраивает или её нужно отключить для диагностики, установите mock.FILTER_DIR = False.

При включённой фильтрации dir(some_mock) показывает только полезные атрибуты и будет включать любые динамически созданные атрибуты, которые обычно не отображаются. Если mock был создан с spec (или, конечно, autospec), то отображаются все атрибуты оригинала, даже если к ним ещё не обращались:

>>> dir(Mock())
['assert_any_call',
 'assert_called_once_with',
 'assert_called_with',
 'assert_has_calls',
 'attach_mock',
 ...
>>> from urllib import request
>>> dir(Mock(spec=request))
['AbstractBasicAuthHandler',
 'AbstractDigestAuthHandler',
 'AbstractHTTPHandler',
 'BaseHandler',
 ...

Многие не очень полезные (частные для Mock, а не для того объекта, который замещается) атрибуты с префиксами из одного и двух подчёркиваний были отфильтрованы из результата вызова dir() для Mock. Если такое поведение не устраивает, его можно отключить, установив переключатель уровня модуля FILTER_DIR:

>>> from unittest import mock
>>> mock.FILTER_DIR = False
>>> dir(mock.Mock())
['_NonCallableMock__get_return_value',
 '_NonCallableMock__get_side_effect',
 '_NonCallableMock__return_value_doc',
 '_NonCallableMock__set_return_value',
 '_NonCallableMock__set_side_effect',
 '__call__',
 '__class__',
 ...

В качестве альтернативы можно просто использовать vars(my_mock) (члены экземпляра) и dir(type(my_mock)) (члены типа), чтобы обойти фильтрацию независимо от mock.FILTER_DIR.

26.4.5.7. mock_open¶

unittest.mock.mock_open(mock=None, read_data=None)¶

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

Аргумент mock – это объект mock для настройки. Если None (значение по умолчанию), то будет создан MagicMock с API, ограниченным методами или атрибутами, доступными для стандартных файловых дескрипторов.

read_data – это строка для методов read(), readline() и readlines() файлового дескриптора, которые должны её возвращать. Вызовы этих методов будут брать данные из read_data, пока они не закончатся. Реализация mock для этих методов довольно проста: каждый раз при вызове mock read_data перематывается в начало. Если требуется более тонкое управление данными, передаваемыми тестируемому коду, придётся настроить этот mock самостоятельно. Если этого недостаточно, один из пакетов для файловой системы в памяти на PyPI может предоставить реалистичную файловую систему для тестирования.

Изменено в версии 3.4: Добавлена поддержка readline() и readlines(). Реализация mock для read() изменена так, чтобы потреблять read_data, а не возвращать его при каждом вызове.

Изменено в версии 3.4.4: Теперь read_data сбрасывается при каждом вызове mock.

Использование open() в качестве контекстного менеджера – отличный способ гарантировать правильное закрытие файловых дескрипторов, и он становится обычной практикой:

with open('/some/path', 'w') as f:
    f.write('something')

Проблема в том, что даже если мы замещаем вызов open(), именно возвращённый объект используется как контекстный менеджер (и у него вызываются __enter__() и __exit__()).

Создание моков для контекстных менеджеров с помощью MagicMock – достаточно распространённая и сложная задача, поэтому вспомогательная функция оказывается полезной.

>>> m = mock_open()
>>> with patch('__main__.open', m, create=True):
...     with open('foo', 'w') as h:
...         h.write('some stuff')
...
>>> m.mock_calls
[call('foo', 'w'),
 call().__enter__(),
 call().write('some stuff'),
 call().__exit__(None, None, None)]
>>> m.assert_called_once_with('foo', 'w')
>>> handle = m()
>>> handle.write.assert_called_once_with('some stuff')

А для чтения файлов:

>>> with patch('__main__.open', mock_open(read_data='bibble'), create=True) as m:
...     with open('foo') as h:
...         result = h.read()
...
>>> m.assert_called_once_with('foo')
>>> assert result == 'bibble'

26.4.5.8. Autospeccing¶

Autospeccing основан на существующей возможности spec в mock. Он ограничивает API mock'ов API исходного объекта (спецификации), но делает это рекурсивно (реализовано лениво), так что атрибуты mock'ов имеют только то же API, что и атрибуты спецификации. Кроме того, замещаемые функции/методы имеют ту же сигнатуру вызова, что и оригиналы, поэтому они возбуждают TypeError при неправильном вызове.

Прежде чем я объясню, как работает автоспекинг, вот почему он нужен.

Mock – очень мощный и гибкий объект, но у него есть два недостатка при использовании для замещения объектов тестируемой системы. Один из этих недостатков связан с API Mock, а другой – более общая проблема использования mock-объектов.

Сначала проблема, специфичная для Mock. Mock имеет два метода проверок, которые чрезвычайно удобны: assert_called_with() и assert_called_once_with().

>>> mock = Mock(name='Thing', return_value=None)
>>> mock(1, 2, 3)
>>> mock.assert_called_once_with(1, 2, 3)
>>> mock(1, 2, 3)
>>> mock.assert_called_once_with(1, 2, 3)
Traceback (most recent call last):
 ...
AssertionError: Expected 'mock' to be called once. Called 2 times.

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

>>> mock = Mock(name='Thing', return_value=None)
>>> mock(1, 2, 3)
>>> mock.assret_called_once_with(4, 5, 6)

Из-за опечатки тесты могут проходить молча и неправильно.

The second issue is more general to mocking. If you refactor some of your code, rename members and so on, any tests for code that is still using the old api but uses mocks instead of the real objects will still pass. This means your tests can all pass even though your code is broken.

Обратите внимание, что это ещё одна причина, по которой нужны интеграционные тесты, а не только модульные. Тестировать всё изолированно – это хорошо, но если вы не тестируете, как ваши модули «соединены вместе», всё ещё остаётся много места для ошибок, которые тесты могли бы выявить.

mock уже предоставляет возможность для решения этой проблемы, называемую speccing. Если использовать класс или экземпляр в качестве spec для mock, то можно обращаться только к тем атрибутам mock, которые существуют в реальном классе:

>>> from urllib import request
>>> mock = Mock(spec=request.Request)
>>> mock.assret_called_with
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'assret_called_with'

Spec применяется только к самому mock, поэтому у нас всё ещё есть та же проблема с любыми методами на mock:

>>> mock.has_data()
<mock.Mock object at 0x...>
>>> mock.has_data.assret_called_with()

Авто-спецификация решает эту проблему. Можно либо передать autospec=True в patch() / patch.object(), либо использовать функцию create_autospec() для создания mock со спецификацией. Если использовать аргумент autospec=True для patch(), то объект, который замещается, будет использоваться как объект спецификации. Поскольку спецификация выполняется «лениво» (спецификация создаётся по мере обращения к атрибутам mock), её можно использовать с очень сложными или глубоко вложенными объектами (например, модулями, которые импортируют модули, которые импортируют модули) без значительного снижения производительности.

Вот пример его использования:

>>> from urllib import request
>>> patcher = patch('__main__.request', autospec=True)
>>> mock_request = patcher.start()
>>> request is mock_request
True
>>> mock_request.Request
<MagicMock name='request.Request' spec='Request' id='...'>

Видно, что request.Request имеет спецификацию. request.Request принимает два аргумента в конструкторе (один из которых – self). Вот что произойдёт, если вызвать его неправильно:

>>> req = request.Request()
Traceback (most recent call last):
 ...
TypeError: <lambda>() takes at least 2 arguments (1 given)

Spec также применяется к инстанцированным классам (т.е. возвращаемому значению specced-моков):

>>> req = request.Request('foo')
>>> req
<NonCallableMagicMock name='request.Request()' spec='Request' id='...'>

Объекты Request не являются вызываемыми, поэтому возвращаемое значение при создании нашего замещённого request.Request – это не вызываемый mock. При наличии спецификации любые опечатки в утверждениях будут вызывать правильную ошибку:

>>> req.add_header('spam', 'eggs')
<MagicMock name='request.Request().add_header()' id='...'>
>>> req.add_header.assret_called_with
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'assret_called_with'
>>> req.add_header.assert_called_with('spam', 'eggs')

Во многих случаях достаточно просто добавить autospec=True к существующим вызовам patch(), и это защитит от ошибок, вызванных опечатками и изменениями API.

Помимо использования autospec через patch() существует create_autospec() для непосредственного создания моков с авто-спецификацией:

>>> from urllib import request
>>> mock_request = create_autospec(request)
>>> mock_request.Request('foo', 'bar')
<NonCallableMagicMock name='mock.Request()' spec='Request' id='...'>

Однако у этого подхода есть оговорки и ограничения, поэтому он не используется по умолчанию. Чтобы узнать, какие атрибуты доступны у объекта спецификации, autospec должен интроспектировать (получать доступ к атрибутам) спецификацию. Когда вы обращаетесь к атрибутам мока, под капотом происходит аналогичный обход оригинального объекта. Если у каких-то из ваших специфицированных объектов есть свойства или дескрипторы, которые могут запускать выполнение кода, то использовать autospec может не получиться. С другой стороны, гораздо лучше проектировать объекты так, чтобы интроспекция была безопасной [4].

Более серьёзная проблема заключается в том, что атрибуты экземпляров часто создаются в методе __init__() и вообще не существуют в классе. autospec не может знать о динамически создаваемых атрибутах и ограничивает API видимыми атрибутами.

>>> class Something:
...   def __init__(self):
...     self.a = 33
...
>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a
...
Traceback (most recent call last):
  ...
AttributeError: Mock object has no attribute 'a'

Существует несколько способов решить эту проблему. Самый простой (хотя и не обязательно наименее раздражающий) – просто установить нужные атрибуты на моке после его создания. То, что autospec не позволяет получать атрибуты, которых нет в спецификации, не мешает вам их устанавливать:

>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a = 33
...

Существует более строгая версия как spec, так и autospec, которая не позволяет устанавливать несуществующие атрибуты. Это полезно, если вы хотите гарантировать, что ваш код устанавливает только допустимые атрибуты, но, очевидно, это блокирует данный конкретный сценарий:

>>> with patch('__main__.Something', autospec=True, spec_set=True):
...   thing = Something()
...   thing.a = 33
...
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'a'

Вероятно, лучший способ решения проблемы – добавить атрибуты класса в качестве значений по умолчанию для членов экземпляра, инициализируемых в __init__(). Обратите внимание, что если устанавливаются только атрибуты по умолчанию в __init__(), то их указание через атрибуты класса (разделяемые между экземплярами, конечно) также быстрее. Например:

class Something:
    a = 33

Это поднимает ещё одну проблему. Довольно часто указывают значение по умолчанию None для членов, которые позже будут объектом другого типа. None бесполезен в качестве спецификации, потому что не позволит обращаться ни к каким атрибутам или методам. Поскольку None никогда не будет полезен как спецификация и, вероятно, указывает на член, который обычно будет другого типа, autospec не использует спецификацию для членов, установленных в None. Они будут просто обычными моками (точнее, MagicMock):

>>> class Something:
...     member = None
...
>>> mock = create_autospec(Something)
>>> mock.member.foo.bar.baz()
<MagicMock name='mock.member.foo.bar.baz()' id='...'>

Если изменение ваших рабочих классов для добавления значений по умолчанию не подходит, то есть другие варианты. Один из них – просто использовать экземпляр в качестве спецификации вместо класса. Другой – создать подкласс рабочего класса и добавить значения по умолчанию в подкласс, не затрагивая рабочий класс. Оба варианта требуют использования альтернативного объекта в качестве спецификации. К счастью, patch() это поддерживает: можно просто передать альтернативный объект в качестве аргумента autospec:

>>> class Something:
...   def __init__(self):
...     self.a = 33
...
>>> class SomethingForTest(Something):
...   a = 33
...
>>> p = patch('__main__.Something', autospec=SomethingForTest)
>>> mock = p.start()
>>> mock.a
<NonCallableMagicMock name='Something.a' spec='int' id='...'>