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):
    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):
    today = date.today()
    return f"{title} — generated on {today}"

copy# test_reports.py
import unittest
from unittest.mock import patch
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):
        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):
        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):
    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):
        # 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):
    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_os)
    # 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, mock_post):
        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, mock_post):
        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
import datetime
import reports

class TestGenerateReportContextManager(unittest.TestCase):

    def test_report_date_is_controlled(self):
        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, MagicMock
import mailer

class TestMailerWithSetup(unittest.TestCase):

    def setUp(self):
        # 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):
        mailer.send_welcome_email('[email protected]')
        self.mock_server.sendmail.assert_called_once()

    def test_smtp_connects_to_correct_host(self):
        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, token):
        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):
        mock_create.return_value = {'id': 'ch_test_abc123', 'status': 'succeeded'}

        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():
    url = os.environ.get('DATABASE_URL')
    if not url:
        raise EnvironmentError("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):
        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):
        with self.assertRaises(EnvironmentError):
            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
import boto3

def list_s3_objects(bucket):
    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):
        # 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):
        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
import requests

def fetch_with_retry(url, attempts=3):
    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):
        # 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):
        # 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):
        # side_effect as a callable: inspect arguments and return accordingly
        def dynamic_response(url, **kwargs):
            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, 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
from notifier import AlertService

class TestAlertServiceAutospec(unittest.TestCase):

    @patch('notifier.AlertService', autospec=True)
    def test_send_called_with_correct_args(self, MockAlertService):
        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):
        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 asyncio
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):
        # Build the chain of async context managers that aiohttp uses.
        mock_response = MagicMock()
        mock_response.json = AsyncMock(return_value={'temp_c': 18.5})

        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

        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:

copy# parser.py
def count_lines(path):
    with open(path, 'r') as f:
        return sum(1 for _ in f)

copy# test_parser.py
import unittest
from unittest.mock import patch, mock_open
import parser

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

class TestCountLines(unittest.TestCase):

    def test_counts_three_lines(self):
        m = mock_open(read_data=FAKE_FILE_CONTENT)
        with patch('builtins.open', m):
            count = parser.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, symbol='$'):
    return f"{symbol}{amount:,.2f}"

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

class TestFormatCurrencySpy(unittest.TestCase):

    def test_called_with_correct_args(self):
        # 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):
        # 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):
        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, listdir):
        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()

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. 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.
4. 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.
5. 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.

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.

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.
• PyPI. mock — Rolling backport of unittest.mock. mock 5.2.0. March 2025.