pytest-mock Usage Guide

pytest-mock is a pytest plugin providing a mocker fixture as a thin wrapper around Python's unittest.mock patching API. It automatically undoes all mocking at the end of each test.

The mocker Fixture

The mocker fixture is the main interface. Request it in your test function:

python

def test_example(mocker):
    # All mocks are automatically cleaned up after this test
    mock_func = mocker.patch("module.function")

Available Fixture Scopes

Fixture	Scope	Use Case
`mocker`	function	Default, per-test mocking
`class_mocker`	class	Share mocks across test class
`module_mocker`	module	Share mocks across test module
`package_mocker`	package	Share mocks across package
`session_mocker`	session	Share mocks across entire session

Patching Methods

mocker.patch(target, ...)

Patch a module-level object by its dotted path:

python

def test_patch(mocker):
    # Patch os.remove function
    mock_remove = mocker.patch("os.remove")
    mock_remove.return_value = None

    os.remove("file.txt")
    mock_remove.assert_called_once_with("file.txt")

mocker.patch.object(target, attribute, ...)

Patch an attribute on an object directly:

python

def test_patch_object(mocker):
    import os
    mock_remove = mocker.patch.object(os, "remove")

    os.remove("file.txt")
    mock_remove.assert_called_once_with("file.txt")

mocker.patch.dict(in_dict, values, clear=False)

Patch a dictionary temporarily:

python

def test_patch_dict(mocker):
    config = {"debug": False}
    mocker.patch.dict(config, {"debug": True})

    assert config["debug"] is True
    # After test, config["debug"] is False again

mocker.patch.multiple(target, **kwargs)

Patch multiple attributes at once:

python

def test_patch_multiple(mocker):
    mocks = mocker.patch.multiple(
        "os",
        remove=mocker.DEFAULT,
        listdir=mocker.DEFAULT
    )

    os.remove("file.txt")
    os.listdir("/tmp")

    mocks["remove"].assert_called_once()
    mocks["listdir"].assert_called_once()

mocker.patch.context_manager(target, attribute, ...)

Same as patch.object but doesn't warn when mock is used as context manager:

python

def test_context_manager(mocker):
    mock_open = mocker.patch.context_manager(builtins, "open")
    # No warning when using `with mock_open(...)`

Common Patch Parameters

Parameter	Description
`new`	Object to replace target with
`return_value`	Value returned when mock is called
`side_effect`	Exception to raise or function to call
`autospec`	Create mock matching target's signature
`spec`	Object to use as specification
`spec_set`	Stricter spec that prevents setting new attributes
`create`	Allow patching non-existent attributes
`new_callable`	Callable to create the mock

Spying with mocker.spy()

Spy wraps the real method while tracking calls:

python

def test_spy(mocker):
    spy = mocker.spy(os.path, "exists")

    # Real method is called
    result = os.path.exists("/tmp")

    # But we can inspect calls
    spy.assert_called_once_with("/tmp")

    # Access return values
    assert spy.spy_return == result
    assert spy.spy_return_list == [result]  # All returns

Spy Attributes

Attribute	Description
`spy_return`	Last return value from real method
`spy_return_list`	List of all return values
`spy_return_iter`	Iterator copy (when `duplicate_iterators=True`)
`spy_exception`	Last exception raised, if any

Spying Iterators

python

def test_spy_iterator(mocker):
    spy = mocker.spy(obj, "get_items", duplicate_iterators=True)

    items = list(obj.get_items())

    # Access a copy of the returned iterator
    spy_items = list(spy.spy_return_iter)

Creating Stubs

mocker.stub(name=None)

Create a stub that accepts any arguments:

python

def test_stub(mocker):
    callback = mocker.stub(name="my_callback")

    some_function(on_complete=callback)

    callback.assert_called_once()

mocker.async_stub(name=None)

Create an async stub:

python

async def test_async_stub(mocker):
    callback = mocker.async_stub(name="async_callback")

    await some_async_function(on_complete=callback)

    callback.assert_awaited_once()

Mock Helpers

mocker.create_autospec(spec, ...)

Create a mock that matches the spec's signature:

python

def test_autospec(mocker):
    mock_obj = mocker.create_autospec(MyClass, instance=True)

    # Calling with wrong arguments raises TypeError
    mock_obj.method()  # OK if method() takes no args

Direct Mock Classes

Access mock classes directly through mocker:

python

def test_mock_classes(mocker):
    mock = mocker.Mock()
    magic_mock = mocker.MagicMock()
    async_mock = mocker.AsyncMock()
    property_mock = mocker.PropertyMock()
    non_callable = mocker.NonCallableMock()

Other Utilities

python

def test_utilities(mocker):
    # Match any argument
    mock.assert_called_with(mocker.ANY)

    # Create call objects for assertion
    mock.assert_has_calls([mocker.call(1), mocker.call(2)])

    # Sentinel objects
    result = mocker.sentinel.my_result

    # Mock file open
    m = mocker.mock_open(read_data="file contents")
    mocker.patch("builtins.open", m)

    # Seal a mock to prevent new attributes
    mocker.seal(mock)

Managing Mocks

mocker.stopall()

Stop all patches immediately:

python

def test_stopall(mocker):
    mocker.patch("os.remove")
    mocker.patch("os.listdir")

    mocker.stopall()  # Both patches stopped

mocker.stop(mock)

Stop a specific patch:

python

def test_stop(mocker):
    mock_remove = mocker.patch("os.remove")

    mocker.stop(mock_remove)  # Only this patch stopped

mocker.resetall()

Reset all mocks without stopping them:

python

def test_resetall(mocker):
    mock_func = mocker.patch("module.func")
    mock_func("arg1")

    mocker.resetall()

    mock_func.assert_not_called()  # Call history cleared

Assertion Methods with pytest Introspection

pytest-mock enhances assertion error messages with pytest's comparison:

python

def test_assertions(mocker):
    mock = mocker.patch("module.func")
    mock("actual_arg")

    # Enhanced error shows diff between expected and actual
    mock.assert_called_with("expected_arg")
    # AssertionError shows:
    # Args:
    # assert ('actual_arg',) == ('expected_arg',)

Available Assertions

Call Assertions:

assert_called() - Called at least once
assert_called_once() - Called exactly once
assert_called_with(*args, **kwargs) - Last call matches
assert_called_once_with(*args, **kwargs) - Called once with args
assert_any_call(*args, **kwargs) - Any call matches
assert_has_calls(calls, any_order=False) - Has specific calls
assert_not_called() - Never called

Async Assertions (for AsyncMock):

assert_awaited()
assert_awaited_once()
assert_awaited_with(*args, **kwargs)
assert_awaited_once_with(*args, **kwargs)
assert_any_await(*args, **kwargs)
assert_has_awaits(calls, any_order=False)
assert_not_awaited()

Configuration Options

In pytest.ini, pyproject.toml, or setup.cfg:

ini

[pytest]
# Enable/disable enhanced assertion messages (default: true)
mock_traceback_monkeypatch = true

# Use standalone mock package instead of unittest.mock (default: false)
mock_use_standalone_module = false

Common Patterns

Patching Where Used (Not Where Defined)

python

# my_module.py
from os.path import exists

def check_file(path):
    return exists(path)

# test_my_module.py
def test_check_file(mocker):
    # Patch where it's used, not where it's defined
    mocker.patch("my_module.exists", return_value=True)
    assert check_file("/any/path") is True

Testing Exceptions

python

def test_exception(mocker):
    mock_func = mocker.patch("module.func")
    mock_func.side_effect = ValueError("error message")

    with pytest.raises(ValueError, match="error message"):
        module.func()

Multiple Return Values

python

def test_multiple_returns(mocker):
    mock_func = mocker.patch("module.func")
    mock_func.side_effect = [1, 2, 3]

    assert module.func() == 1
    assert module.func() == 2
    assert module.func() == 3

Async Function Mocking

python

async def test_async(mocker):
    mock_fetch = mocker.patch("module.fetch_data")
    mock_fetch.return_value = {"data": "value"}

    result = await module.fetch_data()
    assert result == {"data": "value"}

Class Method Mocking

python

def test_class_method(mocker):
    mocker.patch.object(MyClass, "class_method", return_value="mocked")

    assert MyClass.class_method() == "mocked"

Property Mocking

python

def test_property(mocker):
    mock_prop = mocker.patch.object(
        MyClass, "my_property",
        new_callable=mocker.PropertyMock,
        return_value="mocked"
    )

    obj = MyClass()
    assert obj.my_property == "mocked"

Search AI Tools

pytest-mock-guide

Install this agent skill to your Project

SKILL.md

pytest-mock Usage Guide

The mocker Fixture

Available Fixture Scopes

Patching Methods

mocker.patch(target, ...)

mocker.patch.object(target, attribute, ...)

mocker.patch.dict(in_dict, values, clear=False)

mocker.patch.multiple(target, **kwargs)

mocker.patch.context_manager(target, attribute, ...)

Common Patch Parameters

Spying with mocker.spy()

Spy Attributes

Spying Iterators

Creating Stubs

mocker.stub(name=None)

mocker.async_stub(name=None)

Mock Helpers

mocker.create_autospec(spec, ...)

Direct Mock Classes

Other Utilities

Managing Mocks

mocker.stopall()

mocker.stop(mock)

mocker.resetall()

Assertion Methods with pytest Introspection

Available Assertions

Configuration Options

Common Patterns

Patching Where Used (Not Where Defined)

Testing Exceptions

Multiple Return Values

Async Function Mocking

Class Method Mocking

Property Mocking