> **Источник:** https://python-all.ru/3.11/library/unittest.mock.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# [`unittest.mock`](https://python-all.ru/3.11/library/unittest.mock.html#module-unittest.mock) – библиотека mock-объектов

Новое в версии 3.3.

**Исходный код:** [Lib/unittest/mock.py](https://python-all.ru/src/3.11/Lib/unittest/mock.py)

---

[`unittest.mock`](https://python-all.ru/3.11/library/unittest.mock.html#module-unittest.mock) – это библиотека для тестирования в Python. Она позволяет заменять части тестируемой системы mock-объектами и делать утверждения о том, как они были использованы.

[`unittest.mock`](https://python-all.ru/3.11/library/unittest.mock.html#module-unittest.mock) предоставляет базовый класс [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock), устраняя необходимость создания множества заглушек во всём наборе тестов. После выполнения действия можно делать утверждения о том, какие методы/атрибуты использовались и с какими аргументами они были вызваны. Также можно задавать возвращаемые значения и устанавливать нужные атрибуты обычным способом.

Кроме того, mock предоставляет декоратор [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch), который обрабатывает подмену атрибутов модуля и класса в рамках теста, а также [`sentinel`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.sentinel) для создания уникальных объектов. Смотрите [краткое руководство](https://python-all.ru/3.11/library/unittest.mock.html#quick-guide) для примеров использования [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock), [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) и [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch).

Mock разработан для использования с [`unittest`](https://python-all.ru/3.11/library/unittest.html#module-unittest) и основан на шаблоне «действие -\> утверждение» вместо «запись -\> воспроизведение», используемого многими фреймворками для имитации.

Существует обратный порт [`unittest.mock`](https://python-all.ru/3.11/library/unittest.mock.html#module-unittest.mock) для более ранних версий Python, доступный как [mock на PyPI](https://python-all.ru/3.11/library/unittest.mock.html).

## Краткое руководство

Объекты [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) и [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) создают все атрибуты и методы по мере обращения к ним и сохраняют сведения о том, как они использовались. Можно настраивать их, задавая возвращаемые значения или ограничивая доступные атрибуты, а затем делать утверждения о том, как они были использованы:

```python
>>> 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-объекта:

```python
>>> mock = Mock(side_effect=KeyError('foo'))
>>> mock()
Traceback (most recent call last):
 ...
KeyError: 'foo'
```

```python
>>> 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 так, чтобы он брал свою спецификацию из другого объекта. Попытка обратиться к атрибутам или методам mock, которые отсутствуют в спецификации, приведёт к ошибке [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError).

Декоратор/контекстный менеджер [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) упрощает имитацию классов или объектов в тестируемом модуле. Указанный объект заменяется mock-объектом (или другим объектом) во время теста и восстанавливается после его завершения:

```python
>>> 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 моки передаются в декорированную функцию в том же порядке, в котором они применяются (обычный порядок применения декораторов в *Python*). Это означает снизу вверх, поэтому в примере выше mock для `module.ClassName1` передаётся первым.
>
> Для [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) важно, что подменяются объекты в том пространстве имён, где они ищутся. Обычно это понятно, но для быстрого ознакомления прочтите [где делать подмену](https://python-all.ru/3.11/library/unittest.mock.html#where-to-patch).

Помимо использования в качестве декоратора, [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) можно использовать как контекстный менеджер в операторе with:

```python
>>> 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()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.dict) для установки значений в словаре только в пределах области видимости и восстановления словаря в исходное состояние после завершения теста:

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

Mock поддерживает имитацию [магических методов](https://python-all.ru/3.11/library/unittest.mock.html#magic-methods) Python. Самый простой способ использования магических методов – это класс [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock). Он позволяет делать такие вещи, как:

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

Mock позволяет назначать функции (или другие экземпляры Mock) магическим методам, и они будут вызываться должным образом. Класс [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) – это просто разновидность Mock, в которой все магические методы уже предсозданы (ну, по крайней мере, все полезные).

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

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

Чтобы объекты-заглушки в тестах имели тот же API, что и заменяемые объекты, можно воспользоваться [автоспецификацией](https://python-all.ru/3.11/library/unittest.mock.html#auto-speccing). Автоспецификацию можно выполнить через аргумент *autospec* функции patch или через функцию [`create_autospec()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.create_autospec). Автоспецификация создаёт объекты-заглушки с теми же атрибутами и методами, что и заменяемые объекты, а все функции и методы (включая конструкторы) имеют ту же сигнатуру вызова, что и настоящий объект.

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

```python
>>> 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()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.create_autospec) также можно применять к классам – тогда копируется сигнатура метода `__init__`, и к вызываемым объектам – копируется сигнатура метода `__call__`.

## Класс Mock

[`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) – это гибкий объект-заглушка, предназначенный для замены заглушек и тестовых дублёров по всему коду. Заглушки вызываемы и при обращении [\[1\]](https://python-all.ru/3.11/library/unittest.mock.html#id3) создают атрибуты как новые заглушки. Обращение к одному и тому же атрибуту всегда возвращает одну и ту же заглушку. Заглушки записывают, как вы их используете, что позволяет делать утверждения о том, что ваш код с ними сделал.

[`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) – это подкласс [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock), в котором все магические методы уже предопределены и готовы к использованию. Существуют также невызываемые варианты, полезные, когда нужно подменить объекты, которые не вызываются: [`NonCallableMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.NonCallableMock) и [`NonCallableMagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.NonCallableMagicMock).

Декораторы [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) упрощают временную замену классов в конкретном модуле объектом [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock). По умолчанию [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) создаёт для вас [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock). Можно указать альтернативный класс для [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) с помощью аргумента *new\_callable* функции [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch).

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

Создаёт новый объект [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock). [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) принимает несколько необязательных аргументов, задающих поведение объекта Mock:

- *spec*: может быть списком строк или существующим объектом (классом или экземпляром), который служит спецификацией для объекта-заглушки. Если передать объект, список строк формируется вызовом dir у этого объекта (исключая неподдерживаемые магические атрибуты и методы). Обращение к атрибуту, отсутствующему в этом списке, вызовет исключение [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError).

  Если *spec* – объект (а не список строк), то [`__class__`](https://python-all.ru/3.11/library/stdtypes.html#instance.__class__) возвращает класс этого объекта-спецификации. Это позволяет заглушкам проходить проверки [`isinstance()`](https://python-all.ru/3.11/library/functions.html#isinstance).
- *spec\_set*: более строгий вариант *spec*. Если он указан, попытка *установить* или прочитать у заглушки атрибут, отсутствующий у объекта, переданного как *spec\_set*, вызовет [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError).
- *side\_effect*: функция, вызываемая каждый раз при вызове Mock. См. атрибут [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect). Полезна для возбуждения исключений или динамического изменения возвращаемых значений. Функция вызывается с теми же аргументами, что и заглушка, и если она не возвращает [`DEFAULT`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.DEFAULT), то возвращаемое значение этой функции становится возвращаемым значением заглушки.

  Альтернативно *side\_effect* может быть классом исключения или экземпляром. В этом случае исключение будет возбуждено при вызове заглушки.

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

  *side\_effect* можно очистить, установив его равным `None`.
- *return\_value*: значение, возвращаемое при вызове заглушки. По умолчанию это новый Mock (создаётся при первом обращении). См. атрибут [`return_value`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.return_value).
- *unsafe*: по умолчанию обращение к любому атрибуту, имя которого начинается с *assert*, *assret*, *asert*, *aseert* или *assrt*, вызовет исключение [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError). Передача `unsafe=True` разрешит доступ к этим атрибутам.

  Новое в версии 3.5.
- *wraps*: объект, который будет обёрнут заглушкой. Если *wraps* не равен `None`, то вызов Mock передаётся обёрнутому объекту (возвращается реальный результат). Обращение к атрибуту заглушки возвращает объект Mock, который оборачивает соответствующий атрибут обёрнутого объекта (попытка обратиться к несуществующему атрибуту вызовет [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError)).

  Если для заглушки явно задан *return\_value*, то вызовы не передаются обёрнутому объекту, а возвращается значение *return\_value*.
- *name*: если у заглушки есть имя, оно будет использоваться в repr заглушки. Это может быть полезно для отладки. Имя распространяется на дочерние заглушки.

Заглушки также можно вызывать с произвольными именованными аргументами. Они будут использованы для установки атрибутов заглушки после её создания. Подробнее см. метод [`configure_mock()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.configure_mock).

#### `assert_called()`

Утверждает, что заглушка вызывалась хотя бы один раз.

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

Новое в версии 3.6.

#### `assert_called_once()`

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

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

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

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

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

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

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

Утверждение проходит, если макет *когда-либо* вызывался, в отличие от [`assert_called_with()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_called_with) и [`assert_called_once_with()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_called_once_with), которые проходят только в том случае, если вызов является самым последним, а в случае [`assert_called_once_with()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_called_once_with) он также должен быть единственным вызовом.

```python
>>> 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`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls) проверяется на наличие вызовов.

Если *any\_order* имеет значение false, то вызовы должны быть последовательными. Допускаются дополнительные вызовы до или после указанных вызовов.

Если *any\_order* имеет значение true, то вызовы могут быть в любом порядке, но все они должны присутствовать в [`mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls).

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

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

```python
>>> 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 сбрасывает все атрибуты вызовов у макета:

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

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

Это может быть полезно, когда нужно выполнить серию проверок, повторно используя один и тот же объект. Обратите внимание, что [`reset_mock()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.reset_mock) *не* очищает возвращаемое значение, [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect) или любые дочерние атрибуты, которые были назначены обычным присваиванием по умолчанию. Если требуется сбросить *return\_value* или [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect), то передайте соответствующий параметр как `True`. Дочерние имитации и имитация возвращаемого значения (если есть) также сбрасываются.

> **Примечание**
>
> *return\_value* и [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect) – ключевые аргументы.

#### `mock_add_spec(spec, spec_set=False)`

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

Если *spec\_set* имеет значение true, то можно устанавливать только атрибуты, указанные в спецификации.

#### `attach_mock(mock, attribute)`

Прикрепляет макет как атрибут к текущему, заменяя его имя и родителя. Вызовы прикреплённого макета будут записаны в атрибуты [`method_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.method_calls) и [`mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls) текущего макета.

#### `configure_mock(**kwargs)`

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

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

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

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

```python
>>> 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()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.configure_mock) существует для упрощения настройки после создания макета.

#### `__dir__()`

Объекты [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) ограничивают результаты `dir(some_mock)` полезными результатами. Для макетов с *spec* сюда входят все разрешённые атрибуты макета.

Смотрите [`FILTER_DIR`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.FILTER_DIR) о том, что делает эта фильтрация и как её отключить.

#### `_get_child_mock(**kw)`

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

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

#### `called`

Логическое значение, указывающее, был ли вызван mock-объект:

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

#### `call_count`

Целое число, показывающее, сколько раз был вызван mock-объект:

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

#### `return_value`

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

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

Значение по умолчанию – это mock-объект, и его можно настроить обычным способом:

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

[`return_value`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.return_value) также можно установить в конструкторе:

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

#### `side_effect`

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

Если передать функцию, она будет вызвана с теми же аргументами, что и mock, и, если функция не возвращает синглтон [`DEFAULT`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.DEFAULT), вызов mock вернёт результат функции. Если функция возвращает [`DEFAULT`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.DEFAULT), то mock вернёт своё обычное значение (из [`return_value`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.return_value)).

Если передать итерируемый объект, он используется для получения итератора, который должен возвращать значение при каждом вызове. Это значение может быть либо экземпляром исключения для возбуждения, либо значением, возвращаемым из вызова mock (обработка [`DEFAULT`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.DEFAULT) идентична случаю с функцией).

Пример mock-объекта, возбуждающего исключение (для проверки обработки исключений API):

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

Использование [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect) для возврата последовательности значений:

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

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

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

[`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect) можно установить в конструкторе. Вот пример, который добавляет единицу к значению, с которым вызывается mock, и возвращает результат:

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

Установка [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect) в `None` очищает его:

```python
>>> 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`) – это позиционные аргументы, с которыми был вызван фиктивный объект (или пустой кортеж), а второй элемент (также доступен через свойство `kwargs`) – это именованные аргументы (или пустой словарь).

```python
>>> 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`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args), а также элементы списков [`call_args_list`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args_list), [`method_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.method_calls) и [`mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls) являются объектами [`call`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.call). Это кортежи, поэтому их можно распаковать для получения отдельных аргументов и создания более сложных утверждений. См. [вызовы как кортежи](https://python-all.ru/3.11/library/unittest.mock.html#calls-as-tuples).

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

#### `call_args_list`

Это список всех вызовов mock-объекта в порядке их выполнения (поэтому длина списка равна количеству вызовов). До любых вызовов это пустой список. Объект [`call`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.call) можно использовать для удобного создания списков вызовов для сравнения с [`call_args_list`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args_list).

```python
>>> 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`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args_list) являются объектами [`call`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.call). Их можно распаковать как кортежи для получения отдельных аргументов. См. [вызовы как кортежи](https://python-all.ru/3.11/library/unittest.mock.html#calls-as-tuples).

#### `method_calls`

Помимо отслеживания собственных вызовов, mock-объекты также отслеживают вызовы методов и атрибутов, а также *их* методов и атрибутов:

```python
>>> 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`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.method_calls) являются объектами [`call`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.call). Их можно распаковать как кортежи для получения отдельных аргументов. См. [вызовы как кортежи](https://python-all.ru/3.11/library/unittest.mock.html#calls-as-tuples).

#### `mock_calls`

[`mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls) записывает *все* вызовы mock-объекта, его методов, магических методов *и* mock-объектов возвращаемых значений.

```python
>>> 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`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls) являются объектами [`call`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.call). Их можно распаковать как кортежи для получения отдельных аргументов. См. [вызовы как кортежи](https://python-all.ru/3.11/library/unittest.mock.html#calls-as-tuples).

> **Примечание**
>
> Способ записи [`mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls) означает, что при вложенных вызовах параметры вышестоящих вызовов не записываются и поэтому всегда будут сравниваться как равные:
>
> ```python
> >>> 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__`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.__class__) объекта возвращает его тип. Для mock-объекта с `spec`, `__class__` вместо этого возвращает класс спецификации. Это позволяет mock-объектам проходить тесты [`isinstance()`](https://python-all.ru/3.11/library/functions.html#isinstance) для объекта, который они заменяют или под который маскируются:

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

[`__class__`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.__class__) может быть присвоен, что позволяет mock пройти проверку [`isinstance()`](https://python-all.ru/3.11/library/functions.html#isinstance) без необходимости указывать spec:

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

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

Невызываемая версия [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock). Параметры конструктора имеют тот же смысл, что и в [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock), за исключением *return\_value* и *side\_effect*, которые не имеют смысла для невызываемого mock.

Объекты mock, использующие класс или экземпляр в качестве `spec` или `spec_set`, способны проходить тесты [`isinstance()`](https://python-all.ru/3.11/library/functions.html#isinstance):

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

Классы [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) поддерживают имитацию магических методов. Подробнее см. [магические методы](https://python-all.ru/3.11/library/unittest.mock.html#magic-methods).

Классы mock и декораторы [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) принимают произвольные именованные аргументы для настройки. Для декораторов [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) именованные аргументы передаются конструктору создаваемого mock. Именованные аргументы предназначены для настройки атрибутов mock:

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

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

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

Вызываемый mock, созданный с *spec* (или *spec\_set*), будет анализировать сигнатуру объекта спецификации при сопоставлении вызовов с mock. Следовательно, он может сопоставлять аргументы фактического вызова независимо от того, переданы они позиционно или по имени:

```python
>>> 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()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_called_with), [`assert_called_once_with()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_called_once_with), [`assert_has_calls()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_has_calls) и [`assert_any_call()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_any_call). При [автоспецификации](https://python-all.ru/3.11/library/unittest.mock.html#auto-speccing) это также будет применяться к вызовам методов объекта mock.

Изменено в версии 3.4: Добавлен анализ сигнатуры для объектов mock с указанной спецификацией и автоспецификацией.

#### `class unittest.mock.PropertyMock(*args, **kwargs)`

Mock, предназначенный для использования в качестве [`property`](https://python-all.ru/3.11/library/functions.html#property) или другого [дескриптора](https://python-all.ru/3.11/glossary.html#term-descriptor) в классе. [`PropertyMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.PropertyMock) предоставляет методы [`__get__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__get__) и [`__set__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__set__), чтобы можно было указать возвращаемое значение при его получении.

Получение экземпляра [`PropertyMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.PropertyMock) из объекта вызывает mock без аргументов. Установка его вызывает mock с устанавливаемым значением.

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

Из-за способа хранения атрибутов mock нельзя напрямую прикрепить [`PropertyMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.PropertyMock) к объекту mock. Вместо этого можно прикрепить его к объекту типа mock:

```python
>>> 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`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock). Объект [`AsyncMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock) будет вести себя так, что объект будет распознаваться как асинхронная функция, а результат вызова будет ожидаемым объектом.

```python
>>> 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`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock).

Установка *spec* для [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) или [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) в асинхронную функцию приведет к тому, что после вызова будет возвращен объект корутины.

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

Установка *spec* для [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock), [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) или [`AsyncMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock) в класс с асинхронными и синхронными функциями автоматически определит синхронные функции и установит их как [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) (если родительский mock является [`AsyncMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock) или [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock)) или [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) (если родительский mock является [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock)). Все асинхронные функции будут [`AsyncMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock).

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

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

```python
>>> 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 был ожидан ровно один раз.

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

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

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

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

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

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

```python
>>> 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 с указанными вызовами. Список [`await_args_list`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock.await_args_list) проверяется на наличие ожиданий.

Если *any\_order* равно False, то ожидания должны быть последовательными. Дополнительные вызовы могут быть до или после указанных ожиданий.

Если *any\_order* равно True, то ожидания могут быть в любом порядке, но все они должны присутствовать в [`await_args_list`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock.await_args_list).

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

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

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

#### `reset_mock(*args, **kwargs)`

См. [`Mock.reset_mock()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.reset_mock). Также устанавливает [`await_count`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock.await_count) в 0, [`await_args`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock.await_args) в None и очищает [`await_args_list`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock.await_args_list).

#### `await_count`

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

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

#### `await_args`

Это либо `None` (если мок не был ожидан), либо аргументы, с которыми мок был вызван через await в последний раз. Работает так же, как [`Mock.call_args`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args).

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

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

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

### Вызов

Мок-объекты являются вызываемыми. Вызов возвращает значение, установленное как атрибут [`return_value`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.return_value). Значение по умолчанию – новый объект Mock; он создаётся при первом обращении к возвращаемому значению (явно или при вызове мока), но затем сохраняется и возвращается каждый раз.

Вызовы объекта будут записаны в атрибуты, такие как [`call_args`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args) и [`call_args_list`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args_list).

Если установлен [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect), он будет вызван после того, как вызов будет записан, поэтому если `side_effect` вызывает исключение, вызов всё равно будет записан.

Самый простой способ заставить макет вызывать исключение при вызове – сделать [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect) классом или экземпляром исключения:

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

```python
>>> 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`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.DEFAULT):

```python
>>> 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`:

```python
>>> 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`](https://python-all.ru/3.11/library/exceptions.html#StopIteration)):

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

Если какие-либо элементы итератора являются исключениями, они будут вызваны вместо того, чтобы быть возвращёнными:

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

### Удаление атрибутов

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

Возможно, вы захотите, чтобы объект макета возвращал `False` при вызове [`hasattr()`](https://python-all.ru/3.11/library/functions.html#hasattr), или вызывал [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError) при получении атрибута. Это можно сделать, передав объект в качестве `spec` для макета, но это не всегда удобно.

Вы «блокируете» атрибуты, удаляя их. После удаления доступ к атрибуту вызовет [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError).

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

### Имена макетов и атрибут name

Поскольку «name» является аргументом конструктора [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock), если вы хотите, чтобы ваш объект макета имел атрибут «name», вы не можете просто передать его при создании. Есть две альтернативы. Один из вариантов – использовать [`configure_mock()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.configure_mock):

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

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

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

### Прикрепление макетов в качестве атрибутов

Когда вы прикрепляете макет как атрибут другого макета (или как возвращаемое значение), он становится «дочерним» для этого макета. Вызовы дочернего макета записываются в атрибуты [`method_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.method_calls) и [`mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls) родительского. Это полезно для настройки дочерних макетов и последующего их прикрепления к родительскому, или для прикрепления макетов к родительскому, который записывает все вызовы дочерних и позволяет делать утверждения о порядке вызовов между макетами:

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

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

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

Макеты, созданные для вас с помощью [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch), автоматически получают имена. Чтобы прикрепить макеты с именами к родительскому, используйте метод [`attach_mock()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.attach_mock) :

```python
>>> 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](https://python-all.ru/3.11/library/unittest.mock.html#id1)\]

Единственное исключение – это магические методы и атрибуты (те, которые имеют двойные подчёркивания в начале и конце). Mock не создаёт их, а вместо этого вызывает [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError). Это связано с тем, что интерпретатор часто неявно запрашивает эти методы и *очень* путается, получая новый объект Mock, когда ожидает магический метод. Если вам нужна поддержка магических методов, обратитесь к [магическим методам](https://python-all.ru/3.11/library/unittest.mock.html#magic-methods).

## Патчеры

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

### patch

> **Примечание**
>
> Ключ в том, чтобы выполнять патчинг в правильном пространстве имён. Смотрите раздел [где патчить](https://python-all.ru/3.11/library/unittest.mock.html#id6).

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

[`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) работает как декоратор функции, декоратор класса или контекстный менеджер. Внутри тела функции или оператора with *target* заменяется объектом *new*. Когда функция/оператор with завершается, патчинг отменяется.

Если *new* опущен, то цель заменяется на [`AsyncMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock), если патчируемый объект является асинхронной функцией, или на [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) в противном случае. Если [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) используется как декоратор и *new* опущен, созданный макет передаётся в качестве дополнительного аргумента декорируемой функции. Если [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) используется как контекстный менеджер, созданный макет возвращается контекстным менеджером.

*target* должен быть строкой в формате `'package.module.ClassName'`. *target* импортируется, и указанный объект заменяется на объект *new*, поэтому *target* должен быть импортируемым из окружения, в котором вы вызываете [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch). Цель импортируется при выполнении декорированной функции, а не во время декорирования.

Ключевые аргументы *spec* и *spec\_set* передаются в [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock), если patch создаёт его для вас.

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

*new\_callable* позволяет указать другой класс или вызываемый объект, который будет вызван для создания объекта *new*. По умолчанию [`AsyncMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock) используется для асинхронных функций, а [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) – для остальных.

Более мощная форма *spec* – это *autospec*. Если установить `autospec=True`, то макет будет создан со спецификацией от заменяемого объекта. Все атрибуты макета также будут иметь спецификацию соответствующего атрибута заменяемого объекта. Методы и функции, которые имитируются, будут проверять свои аргументы и вызывать [`TypeError`](https://python-all.ru/3.11/library/exceptions.html#TypeError), если они вызываются с неправильной сигнатурой. Для макетов, заменяющих класс, их возвращаемое значение («экземпляр») будет иметь ту же спецификацию, что и класс. Смотрите функцию [`create_autospec()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.create_autospec) и [Autospeccing](https://python-all.ru/3.11/library/unittest.mock.html#auto-speccing).

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

По умолчанию [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) не сможет заменить атрибуты, которые не существуют. Если передать `create=True`, и атрибут не существует, patch создаст этот атрибут при вызове патченной функции и удалит его после завершения патченной функции. Это полезно для написания тестов на атрибуты, которые ваш production-код создаёт во время выполнения. По умолчанию эта возможность отключена, так как может быть опасной. Включив её, можно писать успешные тесты для API, которых на самом деле не существует!

> **Примечание**
>
> Изменено в версии 3.5: При патчинге встроенных функций в модуле не нужно передавать `create=True` – он будет добавлен по умолчанию.

Patch можно использовать как `TestCase` декоратор класса. Он работает путём декорирования каждого тестового метода в классе. Это уменьшает шаблонный код, когда тестовые методы используют общий набор патчей. [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) находит тесты, ища имена методов, начинающиеся с `patch.TEST_PREFIX`. По умолчанию это `'test'`, что соответствует тому, как [`unittest`](https://python-all.ru/3.11/library/unittest.html#module-unittest) находит тесты. Альтернативный префикс можно указать, задав `patch.TEST_PREFIX`.

Patch можно использовать как менеджер контекста с оператором with. В этом случае патч применяется к блоку с отступом после оператора with. Если используется «as», то патченный объект будет привязан к имени после «as»; это очень полезно, когда [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) создаёт мок-объект.

[`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) принимает произвольные именованные аргументы. Они будут переданы в [`AsyncMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock), если патченный объект асинхронный, в противном случае в [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock), или в *new\_callable*, если он указан.

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

[`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) в качестве декоратора функции, создающего мок и передающего его в декорируемую функцию:

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

Патч класса заменяет класс на [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) *экземпляр*. Если класс инстанцируется в тестируемом коде, то будет использован [`return_value`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.return_value) мока.

Если класс инстанцируется несколько раз, можно использовать [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect), чтобы каждый раз возвращать новый мок. В качестве альтернативы можно установить *return\_value* во что угодно.

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

```python
>>> 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()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) заменяет *класс*, то возвращаемое значение созданного мока будет иметь ту же спецификацию.

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

Аргумент *new\_callable* полезен, когда требуется использовать альтернативный класс вместо [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) по умолчанию для создаваемого мока. Например, если нужно использовать [`NonCallableMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.NonCallableMock):

```python
>>> 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`](https://python-all.ru/3.11/library/io.html#io.StringIO):

```python
>>> 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()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) создаёт мок, обычно первым делом нужно настроить мок. Часть этой настройки можно выполнить в вызове patch. Любые произвольные именованные аргументы, переданные в вызов, будут использованы для установки атрибутов созданного мока:

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

Помимо атрибутов созданного мока, такие атрибуты дочерних моков, как [`return_value`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.return_value) и [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect), также можно настроить. Их нельзя передать напрямую как именованные аргументы, но словарь с такими ключами можно развернуть в вызов [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) с помощью `**`:

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

По умолчанию попытка запатчить несуществующую функцию в модуле (или метод, или атрибут в классе) завершится ошибкой [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError):

```python
>>> @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'
```

Но добавление `create=True` в вызов [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) заставит предыдущий пример работать как ожидается:

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

Изменено в версии 3.8: [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) теперь возвращает [`AsyncMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock), если цель является асинхронной функцией.

### patch.object

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

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

[`patch.object()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.object) можно использовать как декоратор, декоратор класса или менеджер контекста. Аргументы *new*, *spec*, *create*, *spec\_set*, *autospec* и *new\_callable* имеют тот же смысл, что и для [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch). Как и [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch), [`patch.object()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.object) принимает произвольные именованные аргументы для настройки создаваемого мок-объекта.

При использовании в качестве декоратора класса [`patch.object()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.object) учитывает `patch.TEST_PREFIX` для выбора методов, которые нужно обернуть.

[`patch.object()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.object) можно вызывать с тремя или двумя аргументами. Форма с тремя аргументами принимает объект для патча, имя атрибута и объект, которым нужно заменить атрибут.

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

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

*spec*, *create* и остальные аргументы [`patch.object()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.object) имеют тот же смысл, что и для [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch).

### patch.dict

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

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

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

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

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

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

[`patch.dict()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.dict) также можно вызывать с произвольными именованными аргументами для установки значений в словаре.

Изменено в версии 3.8: [`patch.dict()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.dict) теперь возвращает пропатченный словарь при использовании в качестве менеджера контекста.

[`patch.dict()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.dict) может использоваться как менеджер контекста, декоратор или декоратор класса:

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

При использовании в качестве декоратора класса [`patch.dict()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.dict) учитывает `patch.TEST_PREFIX` (по умолчанию `'test'`) для выбора методов, которые нужно обернуть:

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

Если требуется использовать другой префикс для тестов, можно указать его патчерам, задав `patch.TEST_PREFIX`. Подробнее о том, как изменить значение, см. в [TEST\_PREFIX](https://python-all.ru/3.11/library/unittest.mock.html#test-prefix).

[`patch.dict()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.dict) позволяет добавлять элементы в словарь или просто даёт тесту изменить словарь, гарантируя, что после завершения теста словарь будет восстановлен.

```python
>>> foo = {}
>>> with patch.dict(foo, {'newkey': 'newvalue'}) as patched_foo:
...     assert foo == {'newkey': 'newvalue'}
...     assert patched_foo == {'newkey': 'newvalue'}
...     # Вы можете добавлять, обновлять или удалять ключи foo (или patched_foo – это тот же словарь).
...     patched_foo['spam'] = 'eggs'
...
>>> assert foo == {}
>>> assert patched_foo == {}
```

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

Ключевые слова можно использовать в вызове [`patch.dict()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.dict) для установки значений в словаре:

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

[`patch.dict()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.dict) можно применять к объектам, похожим на словарь, но не являющимся таковыми. Как минимум, они должны поддерживать получение, установку и удаление элементов, а также либо итерацию, либо проверку принадлежности. Это соответствует магическим методам [`__getitem__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__getitem__), [`__setitem__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__setitem__), [`__delitem__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__delitem__) и либо [`__iter__()`](https://python-all.ru/3.11/library/stdtypes.html#container.__iter__), либо [`__contains__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__contains__).

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

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

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

Используйте [`DEFAULT`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.DEFAULT) в качестве значения, если хотите, чтобы [`patch.multiple()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.multiple) создавал моки автоматически. В этом случае созданные моки передаются в декорированную функцию по ключу, а при использовании [`patch.multiple()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.multiple) в качестве менеджера контекста возвращается словарь.

[`patch.multiple()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.multiple) можно использовать как декоратор, декоратор класса или менеджер контекста. Аргументы *spec*, *spec\_set*, *create*, *autospec* и *new\_callable* имеют тот же смысл, что и для [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch). Эти аргументы применяются ко *всем* патчам, выполняемым с помощью [`patch.multiple()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.multiple).

При использовании в качестве декоратора класса [`patch.multiple()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.multiple) учитывает `patch.TEST_PREFIX` для выбора методов, которые нужно обернуть.

Если требуется, чтобы [`patch.multiple()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.multiple) создавал моки автоматически, можно указать [`DEFAULT`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.DEFAULT) в качестве значения. При использовании [`patch.multiple()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.multiple) в качестве декоратора созданные моки передаются в декорированную функцию по ключу.

```python
>>> 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()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.multiple) можно вкладывать в другие декораторы `patch`, но аргументы, передаваемые по ключу, следует указывать *после* любых стандартных аргументов, созданных [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch):

```python
>>> @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()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.multiple) используется как менеджер контекста, возвращаемое им значение – это словарь, где созданные моки сгруппированы по имени:

```python
>>> 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: start и stop

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

Для их использования вызовите [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch), [`patch.object()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.object) или [`patch.dict()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.dict) как обычно и сохраните ссылку на возвращаемый объект `patcher`. Затем можно вызвать `start()`, чтобы применить патч, и `stop()`, чтобы его отменить.

Если [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) используется для создания мока, этот мок будет возвращён вызовом `patcher.start`.

```python
>>> 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`:

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

> **Внимание**
>
> При использовании этой техники необходимо убедиться, что патч «отменён» вызовом `stop`. Это может быть сложнее, чем кажется, потому что если в методе `setUp` возникнет исключение, `tearDown` не будет вызван. [`unittest.TestCase.addCleanup()`](https://python-all.ru/3.11/library/unittest.html#unittest.TestCase.addCleanup) упрощает задачу:
>
> ```python
> >>> 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
> ...
> ```
>
> В качестве дополнительного бонуса больше не нужно хранить ссылку на объект `patcher`.

Также можно остановить все запущенные патчи с помощью [`patch.stopall()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.stopall).

#### `patch.stopall()`

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

### Патчинг встроенных функций: patch builtins

Можно патчить любые встроенные функции в модуле. В следующем примере патчится встроенная функция [`ord()`](https://python-all.ru/3.11/library/functions.html#ord):

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

### TEST\_PREFIX

Все патчеры можно использовать в качестве декораторов класса. В этом случае они оборачивают каждый тестовый метод класса. Патчеры распознают методы, начинающиеся с `'test'`, как тестовые. Это тот же принцип, по которому [`unittest.TestLoader`](https://python-all.ru/3.11/library/unittest.html#unittest.TestLoader) по умолчанию находит тестовые методы.

Возможно, потребуется использовать другой префикс для тестов. Уведомить патчеры о другом префиксе можно, установив `patch.TEST_PREFIX`:

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

### Вложенные декораторы патча

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

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

```python
>>> @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. Порядок созданных заглушек, передаваемых в тестовую функцию, соответствует этому порядку.

### Где применять патч

[`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) работает, временно заменяя объект, на который указывает *имя*, другим объектом. На один объект может указывать много имён, поэтому для корректной работы патча необходимо заменить имя, используемое тестируемой системой.

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

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

```python
a.py
    -> Defines SomeClass

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

Теперь мы хотим протестировать `some_function`, но подменить `SomeClass` с помощью [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch). Проблема в том, что когда мы импортируем модуль b (а нам придётся это сделать), он импортирует `SomeClass` из модуля a. Если мы используем [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) для подмены `a.SomeClass`, это не повлияет на наш тест: модуль b уже имеет ссылку на *настоящий* `SomeClass`, и может показаться, что наша подмена не сработала.

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

```python
@patch('b.SomeClass')
```

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

```python
@patch('a.SomeClass')
```

### Замена дескрипторов и прокси-объектов

И [patch](https://python-all.ru/3.11/library/unittest.mock.html#patch), и [patch.object](https://python-all.ru/3.11/library/unittest.mock.html#patch-object) корректно заменяют и восстанавливают дескрипторы: методы класса, статические методы и свойства. Заменять их следует на *классе*, а не на экземпляре. Они также работают с *некоторыми* объектами, проксирующими доступ к атрибутам, например, [объект настроек Django](https://python-all.ru/3.11/library/unittest.mock.html).

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

### Подмена магических методов

[`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) поддерживает подмену методов протоколов Python, также известных как [«магические методы»](https://python-all.ru/3.11/glossary.html#term-magic-method). Это позволяет объектам-заглушкам заменять контейнеры и другие объекты, реализующие протоколы Python.

Поскольку магические методы ищутся иначе, чем обычные методы [\[2\]](https://python-all.ru/3.11/library/unittest.mock.html#id9), эта поддержка была реализована специально. Это означает, что поддерживаются только определённые магические методы. Список поддерживаемых методов включает *почти* все. Если каких-то не хватает, пожалуйста, сообщите.

Магические методы подменяются установкой нужного метода в функцию или экземпляр заглушки. Если используется функция, она *должна* принимать `self` в качестве первого аргумента [\[3\]](https://python-all.ru/3.11/library/unittest.mock.html#id10).

```python
>>> def __str__(self):
...     return 'fooble'
...
>>> mock = Mock()
>>> mock.__str__ = __str__
>>> str(mock)
'fooble'
```

```python
>>> mock = Mock()
>>> mock.__str__ = Mock()
>>> mock.__str__.return_value = 'fooble'
>>> str(mock)
'fooble'
```

```python
>>> mock = Mock()
>>> mock.__iter__ = Mock(return_value=iter([]))
>>> list(mock)
[]
```

Один из вариантов использования – подмена объектов, используемых как контекстные менеджеры в операторе [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with):

```python
>>> 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`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.method_calls), но записываются в [`mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls).

> **Примечание**
>
> Если при создании заглушки использовать именованный аргумент *spec*, то попытка установить магический метод, отсутствующий в спецификации, вызовет [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError).

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

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

Изменено в версии 3.8: Добавлена поддержка [`os.PathLike.__fspath__()`](https://python-all.ru/3.11/library/os.html#os.PathLike.__fspath__).

Изменено в версии 3.8: Добавлена поддержка `__aenter__`, `__aexit__`, `__aiter__` и `__anext__`.

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

- `__getattr__`, `__setattr__`, `__init__` и `__new__`
- `__prepare__`, `__instancecheck__`, `__subclasscheck__`, `__del__`

### Магический макет

Существует два `MagicMock` варианта: [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) и [`NonCallableMagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.NonCallableMagicMock).

#### `class unittest.mock.MagicMock(*args, **kw)`

`MagicMock` является подклассом [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) с реализациями по умолчанию большинства [магических методов](https://python-all.ru/3.11/glossary.html#term-magic-method). Можно использовать `MagicMock`, не настраивая магические методы самостоятельно.

Параметры конструктора имеют тот же смысл, что и для [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock).

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

#### `class unittest.mock.NonCallableMagicMock(*args, **kw)`

Невызываемая версия [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock).

Параметры конструктора имеют тот же смысл, что и для [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock), за исключением *return\_value* и *side\_effect*, которые не имеют смысла для невызываемого mock.

Магические методы настраиваются с помощью объектов [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock), поэтому их можно настраивать и использовать обычным образом:

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

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

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

- `__lt__`: [`NotImplemented`](https://python-all.ru/3.11/library/constants.html#NotImplemented)
- `__gt__`: `NotImplemented`
- `__le__`: `NotImplemented`
- `__ge__`: `NotImplemented`
- `__int__`: `1`
- `__contains__`: `False`
- `__len__`: `0`
- `__iter__`: `iter([])`
- `__exit__`: `False`
- `__aexit__`: `False`
- `__complex__`: `1j`
- `__float__`: `1.0`
- `__bool__`: `True`
- `__index__`: `1`
- `__hash__`: хэш по умолчанию для mock
- `__str__`: строковое представление по умолчанию для mock
- `__sizeof__`: размер по умолчанию для mock

Например:

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

Два метода сравнения, `__eq__()` и `__ne__()`, являются особенными. Они выполняют сравнение на равенство по умолчанию по идентичности, используя атрибут [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect), если не изменить их возвращаемое значение на что-то другое:

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

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

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

Если возвращаемое значение *является* итератором, то однократная итерация по нему израсходует его, и последующие итерации приведут к пустому списку:

```python
>>> 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__`

\[[2](https://python-all.ru/3.11/library/unittest.mock.html#id7)\]

Магические методы *должны* искаться в классе, а не в экземпляре. Разные версии Python непоследовательны в применении этого правила. Поддерживаемые методы протокола должны работать во всех поддерживаемых версиях Python.

\[[3](https://python-all.ru/3.11/library/unittest.mock.html#id8)\]

Функция в основном привязана к классу, но каждый экземпляр `Mock` изолирован от остальных.

## Вспомогательные функции

### sentinel

#### `unittest.mock.sentinel`

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

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

Изменено в версии 3.7: Атрибуты `sentinel` теперь сохраняют свою идентичность при их [`copied`](https://python-all.ru/3.11/library/copy.html#module-copy) или [`pickled`](https://python-all.ru/3.11/library/pickle.html#module-pickle).

Иногда при тестировании нужно проверить, что определённый объект передаётся как аргумент другому методу или возвращается. Часто для этого создают именованные sentinel-объекты. [`sentinel`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.sentinel) предоставляет удобный способ создания и проверки идентичности таких объектов.

В этом примере мы применяем монки-патчинг к `method`, чтобы он возвращал `sentinel.some_object`:

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

### DEFAULT

#### `unittest.mock.DEFAULT`

Объект [`DEFAULT`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.DEFAULT) – это предварительно созданный sentinel (фактически `sentinel.DEFAULT`). Он может использоваться функциями [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect), чтобы указать, что следует использовать обычное возвращаемое значение.

### call

#### `unittest.mock.call(*args, **kwargs)`

[`call()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.call) – это вспомогательный объект для упрощения утверждений, для сравнения с [`call_args`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args), [`call_args_list`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args_list), [`mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls) и [`method_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.method_calls). [`call()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.call) также можно использовать с [`assert_has_calls()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_has_calls).

```python
>>> 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()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.call.call_list) возвращает список всех промежуточных вызовов, а также финального вызова.

`call_list` особенно полезен для проверки «цепочных вызовов». Цепочный вызов – это несколько вызовов в одной строке кода. В результате в [`mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls) макета появляется несколько записей. Ручное построение последовательности вызовов может быть утомительным.

[`call_list()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.call.call_list) может построить последовательность вызовов из того же цепочного вызова:

```python
>>> 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`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args), [`Mock.call_args_list`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args_list) и [`Mock.mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls), можно интроспектировать, чтобы получить отдельные аргументы, которые они содержат.

Объекты `call` в [`Mock.call_args`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args) и [`Mock.call_args_list`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args_list) представляют собой кортежи из двух элементов (позиционные аргументы, именованные аргументы), тогда как объекты `call` в [`Mock.mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls), а также создаваемые вручную, являются кортежами из трёх элементов (имя, позиционные аргументы, именованные аргументы).

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

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

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

### create\_autospec

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

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

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

Если *spec\_set* равен `True`, то попытка установить атрибуты, которых нет в объекте спецификации, вызовет исключение [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError).

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

[`create_autospec()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.create_autospec) также принимает произвольные именованные аргументы, которые передаются конструктору создаваемого макета.

Смотрите [Autospeccing](https://python-all.ru/3.11/library/unittest.mock.html#auto-speccing) для примеров использования автоспецификации с [`create_autospec()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.create_autospec) и аргументом *autospec* для [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch).

Изменено в версии 3.8: [`create_autospec()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.create_autospec) теперь возвращает [`AsyncMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.AsyncMock), если цель является асинхронной функцией.

### ANY

#### `unittest.mock.ANY`

Иногда может потребоваться сделать утверждения о *некоторых* аргументах вызова макета, но либо некоторые аргументы не важны, либо нужно извлечь их по отдельности из [`call_args`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.call_args) и сделать более сложные проверки.

Чтобы игнорировать определённые аргументы, можно передавать объекты, которые сравниваются равными с *чем угодно*. Вызовы [`assert_called_with()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_called_with) и [`assert_called_once_with()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_called_once_with) тогда будут успешными независимо от того, что было передано.

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

[`ANY`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.ANY) также можно использовать в сравнениях со списками вызовов, например: [`mock_calls`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.mock_calls):

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

[`ANY`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.ANY) не ограничивается сравнениями с объектами вызовов, поэтому его также можно использовать в утверждениях тестов:

```python
class TestStringMethods(unittest.TestCase):

    def test_split(self):
        s = 'hello world'
        self.assertEqual(s.split(), ['hello', ANY])
```

### FILTER\_DIR

#### `unittest.mock.FILTER_DIR`

[`FILTER_DIR`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.FILTER_DIR) – это переменная уровня модуля, которая управляет тем, как mock-объекты реагируют на [`dir()`](https://python-all.ru/3.11/library/functions.html#dir). По умолчанию используется `True`, который применяет описанную ниже фильтрацию, чтобы показывать только полезные атрибуты. Если вам не нравится эта фильтрация или нужно отключить её для диагностики, установите `mock.FILTER_DIR = False`.

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

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

Многие не очень полезные атрибуты (приватные для [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock), а не для того, что имитируется) с префиксом из одного или двух подчёркиваний были отфильтрованы из результата вызова [`dir()`](https://python-all.ru/3.11/library/functions.html#dir) на [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock). Если вам не нравится такое поведение, вы можете отключить его, установив переключатель уровня модуля [`FILTER_DIR`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.FILTER_DIR):

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

### mock\_open

#### `unittest.mock.mock_open(mock=None, read_data=None)`

Вспомогательная функция для создания mock для замены использования [`open()`](https://python-all.ru/3.11/library/functions.html#open). Она работает для [`open()`](https://python-all.ru/3.11/library/functions.html#open), вызываемого напрямую или используемого как контекстный менеджер.

Аргумент *mock* – это настраиваемый объект mock. Если `None` (по умолчанию), то для вас будет создан [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) с API, ограниченным методами или атрибутами, доступными у стандартных файловых дескрипторов.

*read\_data* – это строка, которую методы `read()`, [`readline()`](https://python-all.ru/3.11/library/io.html#io.IOBase.readline) и [`readlines()`](https://python-all.ru/3.11/library/io.html#io.IOBase.readlines) файлового хендла должны возвращать. Вызовы этих методов будут брать данные из *read\_data*, пока она не исчерпается. Mock этих методов довольно примитивен: каждый раз при вызове *mock* *read\_data* перематывается к началу. Если вам нужен больший контроль над данными, которые вы передаёте тестируемому коду, вам придётся настроить этот mock самостоятельно. Если этого недостаточно, один из пакетов для файловой системы в памяти на [PyPI](https://python-all.ru/3.11/library/unittest.mock.html) может предложить реалистичную файловую систему для тестирования.

Изменено в версии 3.4: Добавлена поддержка [`readline()`](https://python-all.ru/3.11/library/io.html#io.IOBase.readline) и [`readlines()`](https://python-all.ru/3.11/library/io.html#io.IOBase.readlines). Mock для `read()` изменён – теперь он потребляет *read\_data*, а не возвращает её при каждом вызове.

Изменено в версии 3.5: Теперь *read\_data* сбрасывается при каждом вызове *mock*.

Изменено в версии 3.8: Добавлен [`__iter__()`](https://python-all.ru/3.11/library/stdtypes.html#container.__iter__) в реализацию, чтобы итерация (например, в циклах for) корректно потребляла *read\_data*.

Использование [`open()`](https://python-all.ru/3.11/library/functions.html#open) как контекстного менеджера – отличный способ гарантировать, что ваши файловые хендлы будут правильно закрыты, и это становится всё более распространённым:

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

Проблема в том, что даже если вы замокаете вызов [`open()`](https://python-all.ru/3.11/library/functions.html#open), именно *возвращаемый объект* используется как контекстный менеджер (и у него вызываются [`__enter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__enter__) и [`__exit__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__exit__)).

Мокать контекстные менеджеры с помощью [`MagicMock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.MagicMock) достаточно распространено и замороченно, поэтому вспомогательная функция полезна.

```python
>>> m = mock_open()
>>> with patch('__main__.open', m):
...     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')
```

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

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

### Автоспецификация

Autospeccing основан на существующей `spec` функции mock. Он ограничивает API mock-объектов API исходного объекта (spec), но является рекурсивным (реализован лениво), поэтому атрибуты mock имеют только те же API, что и атрибуты spec. Кроме того, замоканные функции/методы имеют ту же сигнатуру вызова, что и оригинал, поэтому они вызывают [`TypeError`](https://python-all.ru/3.11/library/exceptions.html#TypeError), если вызваны неправильно.

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

[`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) – очень мощный и гибкий объект, но у него есть два недостатка при использовании для подмены объектов тестируемой системы. Один из них относится к API [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock), а другой – более общая проблема использования mock-объектов.

Сначала проблема, специфичная для [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock). У [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) есть два очень удобных метода assert: [`assert_called_with()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_called_with) и [`assert_called_once_with()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.assert_called_once_with).

```python
>>> 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-объекты автоматически создают атрибуты по требованию и позволяют вызывать их с произвольными аргументами, опечатка в имени одного из этих методов проверок приводит к тому, что проверка просто исчезает:

```pycon
>>> 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, которые существуют в реальном классе:

```python
>>> 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:

```pycon
>>> mock.has_data()
<mock.Mock object at 0x...>
>>> mock.has_data.assret_called_with()  # Преднамеренная опечатка!
```

Auto-speccing решает эту проблему. Вы можете передать `autospec=True` в [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) / [`patch.object()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch.object) или использовать функцию [`create_autospec()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.create_autospec), чтобы создать mock с spec. Если вы используете аргумент `autospec=True` для [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch), то заменяемый объект будет использоваться как объект spec. Поскольку speccing выполняется «лениво» (spec создаётся по мере доступа к атрибутам mock), вы можете использовать его с очень сложными или глубоко вложенными объектами (например, модулями, которые импортируют модули, которые импортируют модули) без большого удара по производительности.

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

```python
>>> 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` есть spec. `request.Request` принимает два аргумента в конструкторе (один из них – *self*). Вот что произойдёт, если мы попробуем вызвать его неправильно:

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

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

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

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

```python
>>> 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()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch), и это защитит от ошибок из-за опечаток и изменений API.

Помимо использования *autospec* через [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch), существует [`create_autospec()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.create_autospec) для создания autospec-моков напрямую:

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

Однако у этого подхода есть оговорки и ограничения, поэтому он не используется по умолчанию. Чтобы узнать, какие атрибуты доступны у объекта спецификации, autospec должен интроспектировать (получать доступ к атрибутам) спецификацию. Когда вы обращаетесь к атрибутам мока, под капотом происходит аналогичный обход оригинального объекта. Если у каких-то из ваших специфицированных объектов есть свойства или дескрипторы, которые могут запускать выполнение кода, то использовать autospec может не получиться. С другой стороны, гораздо лучше проектировать объекты так, чтобы интроспекция была безопасной [\[4\]](https://python-all.ru/3.11/library/unittest.mock.html#id12).

Более серьёзная проблема заключается в том, что атрибуты экземпляра часто создаются в методе [`__init__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__init__) и вообще не существуют на уровне класса. *autospec* не может знать о динамически созданных атрибутах и ограничивает API только видимыми атрибутами.

```python
>>> 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* не позволяет получать атрибуты, которых нет в спецификации, не мешает вам их устанавливать:

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

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

```python
>>> 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__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__init__). Обратите внимание: если вы устанавливаете только атрибуты по умолчанию в `__init__()`, то предоставление их через атрибуты класса (общие для экземпляров, разумеется) тоже будет быстрее. Например:

```python
class Something:
    a = 33
```

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

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

Если изменение ваших производственных классов для добавления значений по умолчанию вам не по душе, есть и другие варианты. Один из них – просто использовать экземпляр в качестве спецификации вместо класса. Другой – создать подкласс производственного класса и добавить значения по умолчанию в подкласс, не затрагивая производственный класс. Оба варианта требуют использования альтернативного объекта в качестве спецификации. К счастью, [`patch()`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.patch) поддерживает это – можно просто передать альтернативный объект в качестве аргумента *autospec*:

```python
>>> 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='...'>
```

\[[4](https://python-all.ru/3.11/library/unittest.mock.html#id11)\]

Это относится только к классам или уже созданным объектам. Вызов имитированного класса для создания экземпляра мока *не создаёт* реальный экземпляр. Выполняются только обращения к атрибутам – наряду с вызовами [`dir()`](https://python-all.ru/3.11/library/functions.html#dir).

### Запечатывание моков

#### `unittest.mock.seal(mock)`

Функция seal отключает автоматическое создание моков при обращении к атрибуту запечатываемого мока или рекурсивно к любым его атрибутам, которые уже являются моками.

Если экземпляру мока с именем или спецификацией присваивается атрибут, он не будет учитываться в цепочке запечатывания. Это позволяет предотвратить запечатывание части мок-объекта.

```python
>>> mock = Mock()
>>> mock.submock.attribute1 = 2
>>> mock.not_submock = mock.Mock(name="sample_name")
>>> seal(mock)
>>> mock.new_attribute  # Это вызовет AttributeError.
>>> mock.submock.attribute2  # Это вызовет AttributeError.
>>> mock.not_submock.attribute2  # Это не вызовет исключения.
```

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

## Порядок приоритета `side_effect`, `return_value` и *wraps*

Порядок их приоритета:

1. [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect)
2. [`return_value`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.return_value)
3. *wraps*

Если установлены все три, mock вернёт значение из [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect), полностью игнорируя [`return_value`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.return_value) и обёрнутый объект. Если установлены любые два, тот, у которого более высокий приоритет, вернёт значение. Независимо от того, какой был установлен первым, порядок приоритета остаётся неизменным.

```python
>>> from unittest.mock import Mock
>>> class Order:
...     @staticmethod
...     def get_value():
...         return "third"
...
>>> order_mock = Mock(spec=Order, wraps=Order)
>>> order_mock.get_value.side_effect = ["first"]
>>> order_mock.get_value.return_value = "second"
>>> order_mock.get_value()
'first'
```

Поскольку `None` – это значение по умолчанию для [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect), если вы переназначите его значение обратно на `None`, порядок приоритета будет проверяться между [`return_value`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.return_value) и обёрнутым объектом, игнорируя [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect).

```python
>>> order_mock.get_value.side_effect = None
>>> order_mock.get_value()
'second'
```

Если значение, возвращаемое [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect), равно [`DEFAULT`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.DEFAULT), оно игнорируется, и порядок приоритета переходит к следующему элементу для получения возвращаемого значения.

```python
>>> from unittest.mock import DEFAULT
>>> order_mock.get_value.side_effect = [DEFAULT]
>>> order_mock.get_value()
'second'
```

Когда [`Mock`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock) оборачивает объект, значением по умолчанию для [`return_value`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.return_value) будет [`DEFAULT`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.DEFAULT).

```python
>>> order_mock = Mock(spec=Order, wraps=Order)
>>> order_mock.return_value
sentinel.DEFAULT
>>> order_mock.get_value.return_value
sentinel.DEFAULT
```

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

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

```python
>>> order_mock_instance = order_mock()
>>> isinstance(order_mock_instance, Order)
True
>>> order_mock_instance.get_value()
'third'
```

```python
>>> order_mock.get_value.return_value = DEFAULT
>>> order_mock.get_value()
'third'
```

```python
>>> order_mock.get_value.return_value = "second"
>>> order_mock.get_value()
'second'
```

Но если вы присвоите ему `None`, оно не будет проигнорировано, поскольку это явное присваивание. Таким образом, порядок приоритета не перейдёт к обёрнутому объекту.

```python
>>> order_mock.get_value.return_value = None
>>> order_mock.get_value() is None
True
```

Даже если вы установите все три одновременно при инициализации мока, порядок приоритета останется тем же:

```python
>>> order_mock = Mock(spec=Order, wraps=Order,
...                   **{"get_value.side_effect": ["first"],
...                      "get_value.return_value": "second"}
...                   )
...
>>> order_mock.get_value()
'first'
>>> order_mock.get_value.side_effect = None
>>> order_mock.get_value()
'second'
>>> order_mock.get_value.return_value = DEFAULT
>>> order_mock.get_value()
'third'
```

Если [`side_effect`](https://python-all.ru/3.11/library/unittest.mock.html#unittest.mock.Mock.side_effect) исчерпан, порядок приоритета не приведёт к получению значения от последующих элементов. Вместо этого будет возбуждено исключение `StopIteration`.

```python
>>> order_mock = Mock(spec=Order, wraps=Order)
>>> order_mock.get_value.side_effect = ["first side effect value",
...                                     "another side effect value"]
>>> order_mock.get_value.return_value = "second"
```

```python
>>> order_mock.get_value()
'first side effect value'
>>> order_mock.get_value()
'another side effect value'
```

```python
>>> order_mock.get_value()
Traceback (most recent call last):
 ...
StopIteration
```