Python @unittest.mock.patch: Replacing Real Objects with “Mock” Objects During a Test Run

Unit tests are only valuable when they test one thing in isolation. The moment your function reaches out to a database, a live API, the file system, or the system clock, your test is no longer testing your code alone — it is testing every dependency your code touches. @unittest.mock.patch solves this by temporarily swapping any real object in your code's namespace for a controlled substitute, called a mock, for the exact duration of a single test.

unittest.mock has been part of Python's standard library since Python 3.3. The module provides the Mock class, the MagicMock class, and several patching helpers. patch is the most widely used of those helpers. It is a decorator, a context manager, and a callable that returns a patcher object — all three interfaces share the same underlying mechanism. This article walks through each pattern with full, runnable code examples and explains every parameter worth knowing.

What patch Is and How It Works

At the lowest level, patch is a function that performs two operations on a target attribute: it saves the original value, replaces it with a mock, and registers a cleanup function that restores the original when the test scope ends. Python's module system makes this possible because every name a module has imported lives as an attribute on that module object. patch uses getattr to retrieve the original and setattr to install the replacement. When the scope ends, it calls setattr again with the saved original.

The target you provide to patch is a dotted string in the format 'package.module.attribute'. The string must be importable from the environment where the test runs.

The lookup rule: patch where the name is used, not where it is defined

This is the rule that causes the most confusion. Suppose you have a module called reports.py that imports datetime to stamp the current date onto a generated report:

copy# reports.py
import datetime

def generate_report(title: str) -> str:
    today = datetime.date.today()
    return f"{title} — generated on {today}"

When generate_report calls datetime.date.today(), Python looks up the name datetime in reports's namespace, then calls .date.today() on whatever object it finds there. The correct target string is therefore 'reports.datetime', because that is the name inside the module where the lookup actually happens at runtime.

If instead you had written from datetime import date inside reports.py, the local name in reports's namespace would be date, not datetime. In that case the correct target would be 'reports.date'. Patching 'datetime.date' directly would replace the object in the datetime module's namespace, but reports.py already holds its own binding to the original, so your patch would have no effect on it.

copy# reports.py — version 2: uses a direct import
from datetime import date

def generate_report(title: str) -> str:
    today = date.today()
    return f"{title} — generated on {today}"

copy# test_reports.py
import unittest
from unittest.mock import patch, MagicMock
import datetime
import reports

class TestGenerateReport(unittest.TestCase):

    # WRONG: patches datetime.date in the datetime module itself,
    # but reports.py already has its own 'date' binding — no effect.
    @patch('datetime.date')
    def test_wrong_target(self, mock_date: MagicMock) -> None:
        mock_date.today.return_value = datetime.date(2026, 1, 1)
        result = reports.generate_report("Q1 Summary")
        # The real today() is still called; this test does not control the date.

    # CORRECT: patches the 'date' name inside reports's own namespace.
    @patch('reports.date')
    def test_correct_target(self, mock_date: MagicMock) -> None:
        mock_date.today.return_value = datetime.date(2026, 1, 1)
        result = reports.generate_report("Q1 Summary")
        self.assertEqual(result, "Q1 Summary — generated on 2026-01-01")

if __name__ == '__main__':
    unittest.main()

Mock vs MagicMock

When patch replaces your target object, it installs a MagicMock by default. MagicMock is a subclass of Mock with all common dunder methods pre-configured, which means it can be used wherever Python expects magic method support — for example, as a context manager, as an iterable, or in a with statement. A plain Mock does not have these pre-built, so you would need to configure them yourself. For the overwhelming majority of patching scenarios, the default MagicMock is the right choice. Use plain Mock when you specifically want to verify that a mock is not a callable context manager or iterable, which protects against accidentally passing your mock in places that would silently consume those magic methods.

Three Ways to Call patch

1. As a decorator on a test method

This is the most common form. The decorator wraps the test function, starts the patcher before the function body runs, and stops it afterward. Each @patch decorator adds one positional argument to the test method. The argument receives the mock object that was installed in place of the target:

copy# mailer.py
import smtplib

def send_welcome_email(address: str) -> bool:
    with smtplib.SMTP('smtp.example.com', 587) as server:
        server.sendmail('[email protected]', address, 'Welcome!')
    return True

copy# test_mailer.py
import unittest
from unittest.mock import patch, MagicMock
import mailer

class TestSendWelcomeEmail(unittest.TestCase):

    @patch('mailer.smtplib.SMTP')
    def test_sends_to_correct_address(self, mock_smtp_class: MagicMock) -> None:
        # SMTP() is now mock_smtp_class.
        # Calling smtplib.SMTP(...) returns mock_smtp_class.return_value,
        # which is itself a MagicMock that supports the context manager protocol.
        mock_server = mock_smtp_class.return_value.__enter__.return_value

        result = mailer.send_welcome_email('[email protected]')

        self.assertTrue(result)
        mock_smtp_class.assert_called_once_with('smtp.example.com', 587)
        mock_server.sendmail.assert_called_once_with(
            '[email protected]', '[email protected]', 'Welcome!'
        )

if __name__ == '__main__':
    unittest.main()

Stacking multiple decorators

When you need to patch more than one object in the same test, stack @patch decorators. Decorators are applied bottom-up — the decorator closest to the def line is applied first, which means it corresponds to the first extra argument in the method signature. The topmost decorator corresponds to the last argument.

copy# uploader.py
import os
import requests

def upload_file(path: str) -> int:
    if not os.path.exists(path):
        raise FileNotFoundError(path)
    with open(path, 'rb') as f:
        response = requests.post('https://api.example.com/upload', data=f)
    return response.status_code

copy# test_uploader.py
import unittest
from unittest.mock import patch, MagicMock, mock_open
import uploader

class TestUploadFile(unittest.TestCase):

    # Bottom decorator → first mock argument (mock_exists)
    # Top decorator    → last mock argument (mock_post)
    @patch('uploader.requests.post')     # applied second → mock_post
    @patch('uploader.os.path.exists')    # applied first  → mock_exists
    def test_successful_upload(self, mock_exists: MagicMock, mock_post: MagicMock) -> None:
        mock_exists.return_value = True

        mock_response = MagicMock()
        mock_response.status_code = 200
        mock_post.return_value = mock_response

        with patch('builtins.open', mock_open(read_data=b'file content')):
            status = uploader.upload_file('/tmp/report.pdf')

        self.assertEqual(status, 200)
        mock_exists.assert_called_once_with('/tmp/report.pdf')
        mock_post.assert_called_once()

    @patch('uploader.requests.post')
    @patch('uploader.os.path.exists')
    def test_raises_when_file_missing(self, mock_exists: MagicMock, mock_post: MagicMock) -> None:
        mock_exists.return_value = False

        with self.assertRaises(FileNotFoundError):
            uploader.upload_file('/tmp/missing.pdf')

        # requests.post should never have been called
        mock_post.assert_not_called()

if __name__ == '__main__':
    unittest.main()

2. As a context manager

Using patch as a context manager with the with statement gives you fine-grained control over exactly which lines of code run with the mock installed. The mock is only active for the duration of the with block:

copy# test_reports_context.py
import unittest
from unittest.mock import patch, MagicMock
import datetime
import reports

class TestGenerateReportContextManager(unittest.TestCase):

    def test_report_date_is_controlled(self) -> None:
        fixed_date = datetime.date(2026, 6, 15)

        with patch('reports.date') as mock_date:
            mock_date.today.return_value = fixed_date
            result = reports.generate_report("Mid-Year Review")

        # Outside the with block, reports.date is the real datetime.date again.
        self.assertIn("2026-06-15", result)
        self.assertIn("Mid-Year Review", result)

if __name__ == '__main__':
    unittest.main()

The context manager form is particularly readable when you have complex setup logic that should only partially run under a mock, or when you want to mix real and mocked calls within the same test method.

3. As a patcher started and stopped manually

For situations where you need a mock to stay active across multiple test methods — such as in setUp and tearDown — you can call patch directly to get a patcher object, start it explicitly, and stop it in cleanup:

copy# test_service_setup.py
import unittest
from unittest.mock import patch
import mailer

class TestMailerWithSetup(unittest.TestCase):

    def setUp(self) -> None:
        # Start the patcher and register cleanup so tearDown is never forgotten.
        patcher = patch('mailer.smtplib.SMTP')
        self.mock_smtp_class = patcher.start()
        self.addCleanup(patcher.stop)   # addCleanup is safer than tearDown

        # Configure a shared mock server instance for all test methods.
        self.mock_server = self.mock_smtp_class.return_value.__enter__.return_value

    def test_sends_correct_subject(self) -> None:
        mailer.send_welcome_email('[email protected]')
        self.mock_server.sendmail.assert_called_once()

    def test_smtp_connects_to_correct_host(self) -> None:
        mailer.send_welcome_email('[email protected]')
        self.mock_smtp_class.assert_called_with('smtp.example.com', 587)

if __name__ == '__main__':
    unittest.main()

patch.object — patching by object reference

patch.object takes a live Python object and a string attribute name instead of a dotted path string. This is useful when you already have a reference to the class or module you want to patch, and you want your test to fail at load time if the attribute does not exist rather than at runtime:

copy# payment.py
import stripe

class PaymentProcessor:
    def charge(self, amount_cents: int, token: str) -> str:
        charge = stripe.Charge.create(
            amount=amount_cents,
            currency="usd",
            source=token,
        )
        return charge.id

copy# test_payment.py
import unittest
from unittest.mock import patch, MagicMock
import stripe
from payment import PaymentProcessor

class TestPaymentProcessor(unittest.TestCase):

    @patch.object(stripe.Charge, 'create')
    def test_charge_returns_charge_id(self, mock_create: MagicMock) -> None:
        mock_charge = MagicMock()
        mock_charge.id = 'ch_test_abc123'
        mock_create.return_value = mock_charge

        processor = PaymentProcessor()
        charge_id = processor.charge(5000, 'tok_visa')

        self.assertEqual(charge_id, 'ch_test_abc123')
        mock_create.assert_called_once_with(
            amount=5000,
            currency="usd",
            source='tok_visa',
        )

if __name__ == '__main__':
    unittest.main()

patch.dict — patching dictionaries and os.environ

patch.dict patches a dictionary for the duration of the test. Entries you provide are merged in; entries absent from your patch remain unchanged. When the test ends, the dictionary is restored to its original state. This is the standard way to control environment variables in tests without touching os.environ directly:

copy# config.py
import os

def get_database_url() -> str:
    url = os.environ.get('DATABASE_URL')
    if not url:
        raise OSError("DATABASE_URL is not set")
    return url

copy# test_config.py
import unittest
import os
from unittest.mock import patch
from config import get_database_url

class TestGetDatabaseUrl(unittest.TestCase):

    @patch.dict(os.environ, {'DATABASE_URL': 'postgresql://localhost/testdb'})
    def test_returns_database_url(self) -> None:
        url = get_database_url()
        self.assertEqual(url, 'postgresql://localhost/testdb')

    @patch.dict(os.environ, {}, clear=True)   # clear=True removes ALL env vars
    def test_raises_when_var_missing(self) -> None:
        with self.assertRaises(OSError):
            get_database_url()

if __name__ == '__main__':
    unittest.main()

Configuring Mocks: return_value, side_effect, and Assertions

Installing a mock is only half the work. The other half is configuring what the mock does when called, and then asserting that your code interacted with it in the expected way.

return_value

return_value is the value a mock returns every time it is called as a function. You can set it at construction time or afterward. When you patch a class, return_value represents what the class constructor returns — that is, the instance:

copy# inventory.py
from __future__ import annotations
import boto3

def list_s3_objects(bucket: str) -> list[str]:
    s3 = boto3.client('s3')
    response = s3.list_objects_v2(Bucket=bucket)
    return [obj['Key'] for obj in response.get('Contents', [])]

copy# test_inventory.py
import unittest
from unittest.mock import patch, MagicMock
import inventory

class TestListS3Objects(unittest.TestCase):

    @patch('inventory.boto3.client')
    def test_returns_object_keys(self, mock_client_constructor: MagicMock) -> None:
        # mock_client_constructor() is what boto3.client('s3') returns.
        mock_s3 = mock_client_constructor.return_value
        mock_s3.list_objects_v2.return_value = {
            'Contents': [
                {'Key': 'reports/q1.pdf'},
                {'Key': 'reports/q2.pdf'},
            ]
        }

        keys = inventory.list_s3_objects('my-data-bucket')

        self.assertEqual(keys, ['reports/q1.pdf', 'reports/q2.pdf'])
        mock_client_constructor.assert_called_once_with('s3')
        mock_s3.list_objects_v2.assert_called_once_with(Bucket='my-data-bucket')

    @patch('inventory.boto3.client')
    def test_returns_empty_list_when_bucket_empty(self, mock_client_constructor: MagicMock) -> None:
        mock_s3 = mock_client_constructor.return_value
        mock_s3.list_objects_v2.return_value = {}   # no 'Contents' key

        keys = inventory.list_s3_objects('empty-bucket')
        self.assertEqual(keys, [])

if __name__ == '__main__':
    unittest.main()

side_effect

side_effect gives you finer control than return_value. It takes priority over return_value when both are set. There are three forms:

• An exception class or instance: the mock raises it every time it is called.
• A callable: the mock calls it with the same arguments it received and returns the result. This lets you write a real function that inspects the arguments and returns different values.
• An iterable: each successive call to the mock pops the next value from the iterable. If the value is an exception, it is raised rather than returned.

copy# fetcher.py
from __future__ import annotations
import requests

def fetch_with_retry(url: str, attempts: int = 3) -> dict | None:
    for i in range(attempts):
        try:
            response = requests.get(url, timeout=5)
            response.raise_for_status()
            return response.json()
        except requests.RequestException:
            if i == attempts - 1:
                raise
    return None

copy# test_fetcher.py
import unittest
from unittest.mock import patch, MagicMock
import requests
import fetcher

class TestFetchWithRetry(unittest.TestCase):

    @patch('fetcher.requests.get')
    def test_raises_on_connection_error(self, mock_get: MagicMock) -> None:
        # side_effect as an exception: every call raises ConnectionError
        mock_get.side_effect = requests.ConnectionError("refused")

        with self.assertRaises(requests.ConnectionError):
            fetcher.fetch_with_retry('https://api.example.com/data')

        # Three attempts were made before giving up
        self.assertEqual(mock_get.call_count, 3)

    @patch('fetcher.requests.get')
    def test_succeeds_after_two_failures(self, mock_get: MagicMock) -> None:
        # side_effect as an iterable: fail twice, succeed on the third call
        ok_response = MagicMock()
        ok_response.json.return_value = {'status': 'ok'}
        ok_response.raise_for_status.return_value = None

        mock_get.side_effect = [
            requests.ConnectionError("attempt 1"),
            requests.ConnectionError("attempt 2"),
            ok_response,
        ]

        result = fetcher.fetch_with_retry('https://api.example.com/data')

        self.assertEqual(result, {'status': 'ok'})
        self.assertEqual(mock_get.call_count, 3)

    @patch('fetcher.requests.get')
    def test_side_effect_as_callable(self, mock_get: MagicMock) -> None:
        # side_effect as a callable: inspect arguments and return accordingly
        def dynamic_response(url: str, **kwargs: object) -> MagicMock:
            if 'timeout' not in kwargs:
                raise ValueError("timeout required")
            response = MagicMock()
            response.json.return_value = {'url': url}
            response.raise_for_status.return_value = None
            return response

        mock_get.side_effect = dynamic_response

        result = fetcher.fetch_with_retry('https://api.example.com/items')
        self.assertEqual(result['url'], 'https://api.example.com/items')

if __name__ == '__main__':
    unittest.main()

Assertion methods on mocks

Every mock object tracks every call made to it. The following assertion methods are available on any Mock or MagicMock instance, and they raise AssertionError on failure:

autospec — making mocks enforce the real interface

By default, a MagicMock accepts any call with any arguments — a behavior rooted in duck typing principles — because it does not know what the real object's signature looks like. This means your tests can continue to pass after you refactor the real API in a breaking way — the mock never notices. Passing autospec=True to patch tells it to build the mock by inspecting the real object's attributes and method signatures. Calls that do not match the real signature raise TypeError immediately, just as calling the real object with wrong arguments would:

copy# notifier.py
class AlertService:
    def send(self, message: str, priority: int = 1) -> bool:
        # Real implementation would call an external service
        return True

copy# test_notifier_autospec.py
import unittest
from unittest.mock import patch, MagicMock
from notifier import AlertService

class TestAlertServiceAutospec(unittest.TestCase):

    @patch('notifier.AlertService', autospec=True)
    def test_send_called_with_correct_args(self, MockAlertService: MagicMock) -> None:
        instance = MockAlertService.return_value
        instance.send.return_value = True

        service = MockAlertService()
        result = service.send("Disk usage critical", priority=2)

        instance.send.assert_called_once_with("Disk usage critical", priority=2)
        self.assertTrue(result)

    @patch('notifier.AlertService', autospec=True)
    def test_wrong_argument_raises_type_error(self, MockAlertService: MagicMock) -> None:
        instance = MockAlertService.return_value

        # send() does not accept a 'severity' keyword argument.
        # Without autospec this would silently pass.
        # With autospec it raises TypeError immediately.
        with self.assertRaises(TypeError):
            instance.send("High CPU", severity=5)

if __name__ == '__main__':
    unittest.main()

autospec also catches misspelled assertion method names. Without it, writing mock.assert_called_once() when you meant mock.assert_called_once_with(args) silently passes because the mock just creates a new child mock for the unknown attribute. With autospec=True, only methods that exist on the real object are accessible on the mock.

Patching async functions with AsyncMock

When the target is a coroutine function, patch automatically installs an AsyncMock rather than a MagicMock (since Python 3.8). AsyncMock is awaitable and records the same call information. You configure return_value and side_effect in exactly the same way:

copy# async_weather.py
import aiohttp

async def get_temperature(city: str) -> float:
    async with aiohttp.ClientSession() as session:
        async with session.get(f'https://api.weather.example.com/{city}') as resp:
            data = await resp.json()
    return data['temp_c']

copy# test_async_weather.py
import unittest
from unittest.mock import patch, AsyncMock, MagicMock
import async_weather

class TestGetTemperature(unittest.IsolatedAsyncioTestCase):

    @patch('async_weather.aiohttp.ClientSession')
    async def test_returns_temperature(self, MockSession: MagicMock) -> None:
        # Mock the innermost response: resp.json() is a coroutine.
        mock_response = AsyncMock()
        mock_response.json.return_value = {'temp_c': 18.5}

        # async with session.get(...) as resp  →  __aenter__ yields mock_response
        mock_request_cm = MagicMock()
        mock_request_cm.__aenter__ = AsyncMock(return_value=mock_response)
        mock_request_cm.__aexit__ = AsyncMock(return_value=False)

        mock_session = MagicMock()
        mock_session.get.return_value = mock_request_cm

        # async with aiohttp.ClientSession() as session  →  __aenter__ yields mock_session
        mock_session_cm = MagicMock()
        mock_session_cm.__aenter__ = AsyncMock(return_value=mock_session)
        mock_session_cm.__aexit__ = AsyncMock(return_value=False)

        MockSession.return_value = mock_session_cm

        temp = await async_weather.get_temperature('London')
        self.assertEqual(temp, 18.5)

if __name__ == '__main__':
    unittest.main()

mock_open — patching file I/O

unittest.mock.mock_open is a helper that returns a pre-configured mock suitable for replacing Python's built-in open. It handles the context manager protocol and the read(), readline(), and iteration interfaces so you do not need to wire those up yourself. Note that full iteration support — the ability to use mock_open's read_data in a for loop — was added in Python 3.7.1 via __iter__(). On Python 3.7.0 and earlier, looping directly over the mock file object did not consume read_data; only read() and readline() did:

copy# text_utils.py
# NOTE: avoid naming this file parser.py — that shadows the stdlib parser module
# removed in Python 3.12, which can cause confusing ImportErrors.
def count_lines(path: str) -> int:
    with open(path, 'r') as f:
        return sum(1 for _ in f)

copy# test_text_utils.py
import unittest
from unittest.mock import patch, mock_open
import text_utils

FAKE_FILE_CONTENT = "line one\nline two\nline three\n"

class TestCountLines(unittest.TestCase):

    def test_counts_three_lines(self) -> None:
        m = mock_open(read_data=FAKE_FILE_CONTENT)
        with patch('builtins.open', m):
            count = text_utils.count_lines('/fake/path/file.txt')
        self.assertEqual(count, 3)
        m.assert_called_once_with('/fake/path/file.txt', 'r')

if __name__ == '__main__':
    unittest.main()

Additional Parameters: wraps and new_callable

wraps — spy on a real callable without replacing it

The wraps parameter lets you install a mock that delegates every actual call to a real callable, while still recording call information. This is known as a spy: the real function executes and returns its actual result, but the mock wrapper intercepts the call so you can assert on arguments and call count afterward.

This is distinct from autospec=True. With autospec, the real function never runs; with wraps, it always does. Use wraps when you need to verify call behavior against a function whose real side effects are acceptable or necessary in the test environment:

copy# formatter.py
def format_currency(amount: float, symbol: str = '$') -> str:
    return f"{symbol}{amount:,.2f}"

copy# test_formatter_spy.py
import unittest
from unittest.mock import patch, MagicMock
import formatter

class TestFormatCurrencySpy(unittest.TestCase):

    def test_called_with_correct_args(self) -> None:
        # wraps= means the real function still runs; the mock just observes.
        with patch('formatter.format_currency',
                   wraps=formatter.format_currency) as spy:
            result = formatter.format_currency(1234.5)

        # The real function returned the correct string.
        self.assertEqual(result, '$1,234.50')
        # The spy recorded the call.
        spy.assert_called_once_with(1234.5)

if __name__ == '__main__':
    unittest.main()

new_callable — substituting a different mock class

By default, patch() installs a MagicMock. The new_callable parameter lets you substitute a different class. The most common reason to do this is patching a property — Python properties are descriptors, not plain attributes, and replacing them with MagicMock does not wire up the descriptor protocol. PropertyMock is the correct replacement:

copy# server.py
class Server:
    @property
    def is_online(self) -> bool:
        # Real implementation would check a network socket
        return True

copy# test_server.py
import unittest
from unittest.mock import patch, PropertyMock
from server import Server

class TestServer(unittest.TestCase):

    @patch.object(Server, 'is_online', new_callable=PropertyMock)
    def test_offline_branch(self, mock_is_online: PropertyMock) -> None:
        mock_is_online.return_value = False

        s = Server()
        self.assertFalse(s.is_online)
        mock_is_online.assert_called_once()

if __name__ == '__main__':
    unittest.main()

patch.multiple — patching several targets in one call

patch.multiple() accepts a target module and any number of keyword arguments, each naming an attribute to patch in that module. Unlike stacking individual @patch decorators, patch.multiple does not inject mock arguments into the test method unless you pass DEFAULT as the value. This makes it useful for patching several side-effect-prone attributes where you need them replaced but do not need to assert on them individually:

copy# test_multiple.py
import unittest
from unittest.mock import patch, DEFAULT, MagicMock
import os

class TestMultiplePatch(unittest.TestCase):

    # Patch os.getcwd and os.listdir in one decorator call.
    # Passing DEFAULT tells patch.multiple to create a MagicMock and
    # inject it as a keyword argument named after the attribute.
    @patch.multiple('os', getcwd=DEFAULT, listdir=DEFAULT)
    def test_directory_listing(self, getcwd: MagicMock, listdir: MagicMock) -> None:
        getcwd.return_value = '/tmp/project'
        listdir.return_value = ['README.md', 'main.py']

        cwd = os.getcwd()
        files = os.listdir(cwd)

        self.assertEqual(cwd, '/tmp/project')
        self.assertIn('main.py', files)
        getcwd.assert_called_once()

if __name__ == '__main__':
    unittest.main()

ThreadingMock — testing multithreaded call behavior (Python 3.13+)

Python 3.13 added ThreadingMock to unittest.mock. It is a version of MagicMock designed specifically for multithreaded tests, where the normal pattern of asserting immediately after a call does not work because the call you want to verify may not have happened yet — it is happening concurrently on another thread.

ThreadingMock provides wait_until_called() and wait_until_any_call_with() methods that block the test thread until the mock is called — or until an optional timeout expires, at which point they raise AssertionError. This eliminates the need for fragile time.sleep() calls or manual threading.Event coordination in tests that need to verify cross-thread interactions:

copy# worker.py
import threading

def run_in_thread(callback, *args):
    """Runs callback in a daemon thread and returns the thread."""
    t = threading.Thread(target=callback, args=args, daemon=True)
    t.start()
    return t

copy# test_worker.py  — requires Python 3.13+
import unittest
import threading
from unittest.mock import patch, ThreadingMock
import worker

class TestRunInThread(unittest.TestCase):

    def test_callback_called_on_background_thread(self) -> None:
        # ThreadingMock blocks this test thread until the mock is called,
        # rather than asserting immediately (which would be a race condition).
        mock_callback = ThreadingMock()

        t = worker.run_in_thread(mock_callback, 'payload')

        # wait_until_called() blocks until the mock is invoked.
        # Pass timeout= to fail rather than hang if the call never comes.
        mock_callback.wait_until_called(timeout=2)

        t.join()
        mock_callback.assert_called_once_with('payload')

    def test_specific_args_called_on_background_thread(self) -> None:
        mock_callback = ThreadingMock()

        t = worker.run_in_thread(mock_callback, 'event_name', 42)

        # wait_until_any_call_with() blocks until a call matching
        # the specified arguments arrives.
        mock_callback.wait_until_any_call_with('event_name', 42, timeout=2)

        t.join()

if __name__ == '__main__':
    unittest.main()

Three Questions the Patch Documentation Does Not Answer Clearly

create_autospec() — autospec without a patch target

autospec=True inside a patch() call builds the spec automatically from the object being replaced. But there are scenarios where you need a spec'd mock without patching anything — for example, when constructing a dependency in a test's setUp method, or when building a mock to pass directly as an argument. create_autospec() handles this. It takes a real object or class and returns a MagicMock whose attributes, methods, and call signatures mirror those of the original:

copy# storage.py
class BlobStorage:
    def upload(self, key: str, data: bytes, content_type: str = "application/octet-stream") -> str:
        # Real implementation writes to cloud storage
        return f"https://storage.example.com/{key}"

    def delete(self, key: str) -> None:
        pass

copy# test_storage_spec.py
import unittest
from unittest.mock import create_autospec
from storage import BlobStorage

class TestWithCreateAutospec(unittest.TestCase):

    def setUp(self) -> None:
        # create_autospec() builds a mock from the real class signature.
        # No patch() needed — we pass this mock directly to the code under test.
        self.mock_storage = create_autospec(BlobStorage, instance=True)

    def test_upload_called_with_correct_signature(self) -> None:
        self.mock_storage.upload.return_value = "https://storage.example.com/report.pdf"

        result = self.mock_storage.upload("report.pdf", b"data", content_type="application/pdf")
        self.assertEqual(result, "https://storage.example.com/report.pdf")
        self.mock_storage.upload.assert_called_once_with(
            "report.pdf", b"data", content_type="application/pdf"
        )

    def test_wrong_signature_raises(self) -> None:
        # autospec enforces the real signature — extra kwargs raise TypeError
        with self.assertRaises(TypeError):
            self.mock_storage.upload("key.bin", b"data", nonexistent_param=True)

if __name__ == "__main__":
    unittest.main()

Pass instance=True when you want the spec'd mock to behave as an instance of the class rather than as the class itself. Without it, create_autospec(BlobStorage) produces a mock that behaves like the class — callable, returning an instance — which is correct when you are patching the class constructor but wrong when you are substituting an already-instantiated object.

spec vs autospec — what is the difference?

Both spec and autospec constrain what a mock will accept, but they do so at different levels of depth. Understanding the distinction matters when you are choosing between them.

spec restricts attribute access: the mock will raise AttributeError if you access a name that does not exist on the real object. It says nothing about how methods should be called — you can pass any number of arguments to a spec'd method and the mock will not complain. spec is a shallow constraint.

autospec=True (or create_autospec()) goes deeper: it enforces the actual call signature of every method, not just whether the attribute exists. A method declared as def send(self, message, priority=1) will raise TypeError if called with wrong argument count or unknown keyword arguments on an autospecced mock, exactly as the real method would. autospec is a deep constraint:

copy# comparing spec= vs autospec=True
import unittest
from unittest.mock import MagicMock, create_autospec

class Notifier:
    def send(self, message: str, priority: int = 1) -> bool:
        return True

# spec= constrains attribute access only — wrong args still silently pass
spec_mock = MagicMock(spec=Notifier)
spec_mock.send("hello", priority=1, unknown_kwarg="oops")  # no error raised

# autospec enforces the real signature — wrong args raise TypeError immediately
auto_mock = create_autospec(Notifier, instance=True)
try:
    auto_mock.send("hello", priority=1, unknown_kwarg="oops")
except TypeError as e:
    print(f"autospec caught bad kwarg: {e}")
# Output: autospec caught bad kwarg: send() got an unexpected keyword argument 'unknown_kwarg'

The practical guideline is: use autospec=True by default in new test code. Use plain spec= only in the narrow case where you specifically need attribute restriction without signature enforcement — for example, when patching an interface that uses *args, **kwargs throughout and signature checking would always pass.

The assert_called_once typo trap

One of the longest-standing silent failure modes in Python testing is writing mock.assert_called_once() as a standalone statement — with no parentheses on a method that does not exist. Before Python 3.5, a plain MagicMock accepted attribute access on any name and returned a new child mock. So mock.assert_called_once without () silently evaluated to a truthy child mock and the test passed regardless of whether the mock was ever called. Even with parentheses, assert_called_once() is a different method from assert_called_once_with() — the former checks only call count; the latter checks both count and arguments. These are distinct methods and both are valid, but they are frequently confused:

copy# assert_called_once vs assert_called_once_with — illustrated
import unittest
from unittest.mock import MagicMock

class TestAssertionTrap(unittest.TestCase):

    def test_assert_called_once_checks_count_only(self) -> None:
        mock_fn = MagicMock()
        mock_fn("wrong_arg")

        # This passes — called exactly once, regardless of arguments.
        mock_fn.assert_called_once()

        # This would FAIL — called once but not with the expected argument.
        # mock_fn.assert_called_once_with("expected_arg")   # raises AssertionError

    def test_assert_called_once_with_checks_both(self) -> None:
        mock_fn = MagicMock()
        mock_fn("correct_arg")

        # This passes — called once AND with the right argument.
        mock_fn.assert_called_once_with("correct_arg")

    def test_misspelled_assert_raises_attribute_error(self) -> None:
        mock_fn = MagicMock()
        mock_fn("data")

        # Since Python 3.5, accessing a name starting with "assert" that does
        # not exist on Mock raises AttributeError rather than silently returning
        # a child mock. This surfaces the typo at test runtime.
        with self.assertRaises(AttributeError):
            mock_fn.assert_called_onec_with("data")   # typo: 'onec'

if __name__ == "__main__":
    unittest.main()

Since Python 3.5, the mock library raises AttributeError when you access an attribute whose name begins with assert, assret, asert, aseert, or assrt but is not a real assertion method. This catches the most common typos at test runtime rather than silently passing them. The defense is to use autospec=True in addition — an autospecced mock only exposes assertion methods that exist on the real object, eliminating the entire category of fabricated method names.

patch('builtins.X') — patching built-in functions

Built-in functions like open, input, print, and len live in the builtins module. Patching them follows exactly the same where-it-is-looked-up rule as any other name — but because every Python module implicitly imports from builtins, the target is simply 'builtins.open' regardless of which module you are testing. You do not need to qualify it with your module name:

copy# cli.py
def prompt_for_name() -> str:
    name = input("Enter your name: ")
    return name.strip().title()

copy# test_cli.py
import unittest
from unittest.mock import patch
import cli

class TestPromptForName(unittest.TestCase):

    @patch("builtins.input", return_value="  alice smith  ")
    def test_strips_and_titles(self, mock_input: object) -> None:
        result = cli.prompt_for_name()
        self.assertEqual(result, "Alice Smith")
        mock_input.assert_called_once_with("Enter your name: ")

    @patch("builtins.print")
    def test_print_called(self, mock_print: object) -> None:
        # Patching print lets you assert on what your code outputs
        # without capturing stdout.
        print("hello from test")
        mock_print.assert_called_once_with("hello from test")

if __name__ == "__main__":
    unittest.main()

Key Takeaways

1. Patch where the name is looked up, not where it is defined. The target string must point to the attribute in the namespace that the code under test will access at runtime. A from x import y import creates a local binding in the importing module; patch that binding, not x.y in the original module.
2. Use autospec=True to protect against interface drift. A plain MagicMock accepts any call regardless of argument count or attribute name. autospec=True builds the mock from the real object's signature so that breaking refactors are caught by tests rather than silently passing.
3. Use create_autospec() when you need a spec'd mock without a patch target. When constructing a dependency directly in setUp or passing a mock as an argument rather than patching a module, create_autospec(MyClass, instance=True) gives you the same signature enforcement as autospec=True without requiring a dotted string target path.
4. Prefer autospec over plain spec. spec= restricts attribute access only; autospec=True additionally enforces method call signatures. Wrong keyword arguments and incorrect argument counts slip past spec= silently.
5. Prefer side_effect for exception simulation and sequential return values. Set side_effect to an exception class to simulate failures, to an iterable to return different values on successive calls, or to a callable when the response depends on the arguments received. side_effect takes precedence over return_value when both are set.
6. Use wraps when you need real behavior plus call observability. Unlike replacing a function entirely, wraps delegates to the real callable while the mock records the interaction — a targeted spy that does not change program output.
7. Always register cleanup with addCleanup when starting patchers manually. When using patcher.start() in setUp, call self.addCleanup(patcher.stop) rather than relying on tearDown. Cleanup functions run even when setUp raises midway, preventing leaked patches from contaminating subsequent tests.
8. Distinguish assert_called_once() from assert_called_once_with(). The former verifies only call count; the latter verifies both count and arguments. They are separate methods. Use autospec=True as an additional safeguard — it prevents attribute access on non-existent assertion method names that would otherwise silently pass.
9. Patch builtins at builtins.X, not in the calling module. Built-in functions like open, input, and print are resolved from the builtins namespace, so the patch target is always 'builtins.open' — no module prefix needed. Since Python 3.5, create=True is not required for builtins.
10. Use ThreadingMock (Python 3.13+) when the call under test happens on a background thread. Standard mock assertions are immediate; if a callback fires concurrently, the assertion races the call. ThreadingMock.wait_until_called(timeout=N) blocks the test thread until the mock is invoked or the timeout expires, making concurrent call assertions deterministic without time.sleep().

Controlled isolation through @unittest.mock.patch is what separates a test that verifies your logic from a test that verifies your infrastructure. Once you internalize the lookup rule, the decorator stacking order, and the return_value/side_effect distinction, the entire module becomes a straightforward and powerful tool for writing deterministic, fast, and dependency-free unit tests.

How to Use Python @unittest.mock.patch

1. Import patch from unittest.mock. Add from unittest.mock import patch at the top of your test file. The patch function has been part of Python's standard library since version 3.3 and requires no additional installation.
2. Identify the correct patch target. Determine the dotted string path to the object as it is used inside the module under test — not where it is defined. The format is 'package.module.attribute'. Always patch where the name is looked up at runtime, not where the object originates.
3. Apply @patch as a decorator and accept the mock argument. Decorate your test method with @patch('your.target.path'). Add an extra parameter to your test function — it receives the MagicMock instance that replaced the real object for the duration of the test.
4. Configure return_value or side_effect. Set mock.return_value to control what the mocked callable returns. Set mock.side_effect to raise an exception, cycle through multiple return values, or delegate to a callable. side_effect takes precedence over return_value when both are set.
5. Assert call behavior after executing the code under test. Use assert_called_once(), assert_called_with(), assert_called_once_with(), call_count, and call_args to verify the mock was invoked correctly. Add autospec=True to catch interface drift between your mocks and the real objects they replace.
6. Use ThreadingMock for concurrent call assertions (Python 3.13+). When the call you want to assert fires on a background thread, substitute ThreadingMock for MagicMock. Call wait_until_called(timeout=N) after launching the thread to block the test until the mock is invoked, making the assertion deterministic.

Frequently Asked Questions

Sources and References

• Python Software Foundation. unittest.mock — mock object library. Python 3 Standard Library Documentation. Retrieved March 2026.
• Python Software Foundation. unittest.mock — getting started. Python 3 Standard Library Documentation. Retrieved March 2026.
• Python Software Foundation. What's New in Python 3.8. Python 3 Documentation. AsyncMock and IsolatedAsyncioTestCase added in 3.8. Retrieved March 2026.
• Python Software Foundation. What's New in Python 3.13. Python 3 Documentation. ThreadingMock added in 3.13. Retrieved March 2026.
• PyPI. mock — Rolling backport of unittest.mock. mock 5.2.0. March 2025.
• Meszaros, Gerard. xUnit Test Patterns: Refactoring Test Code. Addison-Wesley, 2007. ISBN 978-0-13-149505-0. Source of the canonical test doubles taxonomy: dummy, fake, stub, spy, and mock.