Mocking in Python: unittest.mock and pytest-mock Guide

When writing unit tests, you want to test a single unit of code in isolation. But real-world code often depends on external systems: databases, APIs, file systems, or even the current time. If you test against the real thing, your tests become slow, unreliable, and dependent on infrastructure. That's where mocking comes in.

Mocking allows you to replace real objects with fake ones that mimic their behavior. You can control what they return, what side effects they have, and later assert that they were called correctly. Python's standard library provides unittest.mock, and the pytest ecosystem offers pytest-mock for a more seamless experience.

In this tutorial, you'll learn how to use both libraries effectively. We'll cover creating mock objects, patching imports, setting return values and side effects, and advanced techniques like spies and autospec. You'll also see real-world production incidents where mocking saved the day—or where improper mocking caused bugs.

By the end, you'll be able to write robust, isolated tests that run fast and give you confidence in your code. Let's dive in.

Setting Up Mock Objects with unittest.mock

The unittest.mock module provides the Mock class, which can simulate any object. You can create a mock and set its return value or side effects.

Let's start with a simple example: mocking a function that fetches data from an API.

from unittest.mock import Mock

def fetch_data(api_client):
    return api_client.get('/data')

# Create a mock client
mock_client = Mock()
mock_client.get.return_value = {'key': 'value'}

result = fetch_data(mock_client)
print(result)
print(mock_client.get.called)
print(mock_client.get.call_args)

Patching with unittest.mock.patch

patch temporarily replaces a target with a mock during a test. It can be used as a decorator or context manager. The target is a string in the form 'package.module.ClassName'. It's crucial to patch where the object is used, not where it's defined.

Example: patching datetime.datetime.now to return a fixed date.

from unittest.mock import patch
from datetime import datetime

def get_timestamp():
    return datetime.now().isoformat()

with patch('datetime.datetime') as mock_dt:
    mock_dt.now.return_value = datetime(2025, 1, 1)
    print(get_timestamp())

Using pytest-mock for Cleaner Tests

pytest-mock provides a mocker fixture that wraps unittest.mock and integrates seamlessly with pytest. It automatically cleans up after the test.

Example: testing a function that sends an email.

import pytest
from myapp import send_welcome_email

def test_send_welcome_email(mocker):
    mock_smtp = mocker.patch('myapp.smtplib.SMTP')
    mock_smtp_instance = mock_smtp.return_value
    send_welcome_email('user@example.com')
    mock_smtp_instance.sendmail.assert_called_once()
    args, _ = mock_smtp_instance.sendmail.call_args
    assert 'Welcome' in args[2]

Controlling Return Values and Side Effects

Mocks can return fixed values, raise exceptions, or yield multiple values on successive calls. Use return_value for a single return, and side_effect for more complex behavior.

Example: simulating a database that returns different results on each call.

from unittest.mock import Mock

def get_users(db):
    return [db.fetch_one(), db.fetch_one()]

mock_db = Mock()
mock_db.fetch_one.side_effect = [{'id': 1}, {'id': 2}]

users = get_users(mock_db)
print(users)

# Raise an exception on third call
mock_db.fetch_one.side_effect = [{'id': 1}, {'id': 2}, Exception('DB down')]
try:
    get_users(mock_db)
except Exception as e:
    print(e)

Asserting Calls and Using Spies

After a test, you can assert that mocks were called with specific arguments, call counts, and order. Spies wrap a real object and record calls without replacing behavior.

Example: using wraps to create a spy.

from unittest.mock import Mock

def original(x):
    return x * 2

mock = Mock(wraps=original)
print(mock(5))
print(mock(3))
mock.assert_any_call(5)
mock.assert_any_call(3)
print(mock.call_count)

Autospec and Spec: Preventing Mock Drift

When you create a mock without a spec, it accepts any attribute or method call. This can hide bugs if the real API changes. autospec automatically creates a mock that matches the interface of the original object.

Example: using autospec with patch.

from unittest.mock import patch

class MyAPI:
    def fetch(self, id):
        return {'id': id}

# Without autospec, this passes even though method name is wrong
with patch('__main__.MyAPI', autospec=True) as MockAPI:
    api = MockAPI()
    # api.fetech(1)  # Would raise AttributeError because 'fetech' doesn't exist
    api.fetch(1)  # Works
    MockAPI.assert_called_once()