pytest-mock

3.15.1 · active · verified Sat Mar 28

pytest-mock is a pytest plugin that provides a `mocker` fixture, acting as a thin wrapper around Python's `unittest.mock` library. It simplifies the process of creating and managing mock objects in pytest tests by automatically cleaning up mocks after each test. The library is actively maintained, with frequent updates to support new Python and pytest versions, currently at version 3.15.1.

Warnings

breaking Support for older Python versions is frequently dropped. Python 3.8 support was dropped in v3.15.0, Python 3.7 in v3.12.0, and Python 3.5 in v3.6.0.
Fix: Ensure your project runs on a supported Python version (currently >=3.9 for v3.15.1).
breaking When using `mocker.spy` on functions that return iterators (e.g., `itertools._tee` objects), you now must explicitly pass `duplicate_iterators=True` to avoid `AttributeError` when accessing `spy_return` or `spy_return_iter`.
Fix: For `mocker.spy` calls on iterators, update to `mocker.spy(obj, 'method', duplicate_iterators=True)`.
breaking pytest-mock now requires `pytest>=6.2.5`. Older pytest versions will cause installation or runtime issues.
Fix: Upgrade your pytest installation: `pip install --upgrade pytest`.
breaking The `setup.py` file was removed. Projects relying on `setup.py install` or similar direct invocations will need to update their build process to use standard `pip install` or `pyproject.toml` based builds.
Fix: Refer to the Python packaging documentation or project's `pyproject.toml` for modern installation methods. Avoid direct `python setup.py install`.
gotcha Prior to v3.14.0, `mocker.patch.object` could sometimes fail to be properly cleared between tests, leading to unexpected test interactions or failures.
Fix: Upgrade to `pytest-mock>=3.14.0` to ensure `mocker.patch.object` is correctly cleared. Manually call `mocker.stopall()` or ensure mocks are short-lived if upgrading is not an option.
gotcha While `unittest.mock` supports decorators and context managers for patching, `pytest-mock` prefers the `mocker` fixture. Using `mock.patch` as a decorator or context manager directly with `pytest-mock` may cause warnings or unexpected behavior, as the fixture handles cleanup automatically.
Fix: Always prefer `mocker.patch()`, `mocker.patch.object()`, etc., within your test functions rather than `unittest.mock` decorators or `with patch(...)` statements when using `pytest-mock`.

Install

pip install pytest-mock Install stable version

Imports

mocker
```
def test_example(mocker): ...
```
The `mocker` fixture is automatically provided by pytest-mock; no explicit import statement is usually needed for the fixture itself.
MockType
```
from pytest_mock import MockType
```
Available for type annotation purposes since v3.14.0.
AsyncMockType
```
from pytest_mock import AsyncMockType
```
Available for type annotation purposes since v3.14.0.

Quickstart

This quickstart demonstrates using the `mocker` fixture to patch `os.path.exists` and `builtins.open` to simulate file system interactions without touching actual files. The first test verifies behavior when a file exists, and the second when it doesn't. `mocker.patch` automatically handles cleanup after each test.

import os

class MyService:
    def read_config(self, filename):
        if not os.path.exists(filename):
            return {}
        with open(filename, 'r') as f:
            return {'data': f.read()}

def test_read_config_file_exists(mocker):
    mock_exists = mocker.patch('os.path.exists', return_value=True)
    mock_open = mocker.patch('builtins.open', mocker.mock_open(read_data='key: value'))

    service = MyService()
    result = service.read_config('config.txt')

    mock_exists.assert_called_once_with('config.txt')
    mock_open.assert_called_once_with('config.txt', 'r')
    assert result == {'data': 'key: value'}

def test_read_config_file_not_exists(mocker):
    mocker.patch('os.path.exists', return_value=False)
    mocker.patch('builtins.open', side_effect=FileNotFoundError)

    service = MyService()
    result = service.read_config('non_existent.txt')

    assert result == {}

view raw JSON →