pytest-mock — mocker fixture

Introduction to Patching with Mocker

At its core, the 'mocker' fixture is a thin wrapper around the standard library's patching capabilities, specifically designed to handle the setup and teardown lifecycle automatically. When you patch an object using 'mocker.patch', the plugin tracks that modification and ensures that the original state of the object is restored immediately after the test completes. This is vital for maintaining test isolation, preventing side effects from leaking into subsequent test cases. Understanding that 'mocker' is effectively managing the 'unittest.mock' patcher simplifies the reasoning process: you are temporarily replacing a lookup path in a module with a mock object. Because Python modules import names into their namespace, you must patch the object where it is used, not where it is defined. This mechanism provides a robust way to intercept calls and inspect arguments, ensuring your logic behaves correctly without triggering actual heavy lifting.

# Example: Patching a simple function call
import my_app

def test_process_data(mocker):
    # Patch 'calculate' in the 'my_app' namespace
    mock_calc = mocker.patch('my_app.calculate', return_value=42)
    
    result = my_app.process_data(10)
    
    assert result == 42
    # Verify that the function was called exactly once
    mock_calc.assert_called_once_with(10)

Managing Return Values and Exceptions

When isolating code, you often need to simulate scenarios that are difficult to trigger in real life, such as network timeouts or database connection failures. The 'mocker' fixture allows you to define these behaviors precisely using 'return_value' or 'side_effect'. By using 'side_effect', you can configure a mock to raise an exception when called, which allows you to test your error-handling logic and recovery paths without needing an actual failing system. The core principle here is control: by asserting that your application catches the specific exceptions you defined, you verify that your error handling is not just theoretical. This ensures that even under stress or failure conditions, your system preserves data integrity and reports errors correctly. Because 'mocker' takes care of resetting the state, each test starts with a clean slate, allowing you to chain multiple tests with different side effects without cross-contamination.

# Example: Triggering an exception
import requests
import my_app

def test_api_failure(mocker):
    # Simulate a network timeout error
    mocker.patch('requests.get', side_effect=TimeoutError('Connection failed'))
    
    # Assert that our application handles the error gracefully
    assert my_app.fetch_status() == 'System Unavailable'

Patching Objects and Methods

Beyond simple functions, real-world applications rely heavily on class methods and objects. Patching a method within a class requires careful attention to the attribute path. When you use 'mocker.patch.object', you are targeting a specific instance or class rather than a string path in a module. This is particularly useful when you have an object already instantiated in your test scope. By targeting the object directly, you avoid issues with circular imports or complex namespace resolution. The 'mocker' fixture makes this intuitive: once the patch is applied, every call made to that method on the target instance is routed to your mock. This allows you to verify that internal state transitions occur correctly, or that specific method chains are triggered as expected. It is an essential technique for mocking internal service components while leaving the rest of the application object graph untouched, providing high-fidelity unit testing.

# Example: Patching a class method
class DataProcessor:
    def save(self, data): return True

def test_save_method(mocker):
    processor = DataProcessor()
    # Patch the 'save' method on the instance
    mocker.patch.object(processor, 'save', return_value=False)
    
    assert processor.save("test") is False

Spying on Existing Functions

Sometimes, you do not want to replace the behavior of a function, but merely observe how it is called. This is where 'mocker.spy' becomes an indispensable tool. A spy wraps an existing function, allowing it to execute its real logic while simultaneously recording every invocation, argument passed, and return value. This is powerful for verifying interactions between components in integration-style unit tests where the original logic is necessary for the test to proceed. By using a spy, you maintain the functional integrity of the code while gaining full visibility into the call history. This avoids the common trap of 'over-mocking', where tests become brittle because they describe how a function is called rather than what it achieves. Spying allows you to assert on behavior without sacrificing the real implementation, creating a bridge between simple unit tests and full-scale integration tests.

# Example: Using a spy to record calls
def real_worker(): return "done"

def test_spy_example(mocker):
    # Create a spy on the existing function
    spy = mocker.spy(locals(), 'real_worker')
    
    res = real_worker()
    
    assert res == "done"
    assert spy.called # Verify it was executed

Advanced Mocking Patterns

As your test suite grows, you may encounter scenarios where you need to return different values on consecutive calls, or dynamically generate return values based on input arguments. 'mocker' supports this through advanced configurations of 'side_effect'. By passing an iterable to 'side_effect', you can simulate a stream of data that returns a new item every time the mock is called, eventually raising an 'StopIteration' or simply reusing the last value. Furthermore, you can pass a function to 'side_effect' that computes a return value based on the arguments received by the mock. This provides the ultimate flexibility, allowing your mocks to behave like lightweight, context-aware doubles. Mastering these patterns allows you to simulate complex state machines, retry logic, and pagination workflows. By leveraging these advanced features, you create tests that are both expressive and deeply representative of your application's actual runtime dynamics.

# Example: Dynamic side effects
def test_dynamic_behavior(mocker):
    mock_func = mocker.Mock()
    # Return values sequentially
    mock_func.side_effect = [1, 2, 3]
    
    assert mock_func() == 1
    assert mock_func() == 2
    assert mock_func() == 3

Interview questions

All pytest & Testing interview questions →

Check yourself

Take the full pytest & Testing quiz →