Patching — the @patch Decorator

• Replace a function/object with @patch for one test.
• Apply the "patch where it's used" rule.
• Use patch as a decorator, context manager, or fixture.
• Use autospec=True to catch bad mock usage.

# app.py
import requests

def get_user_count():
    resp = requests.get("https://api.example.com/users")   # hard-wired call
    return len(resp.json())

There's no dependency to inject — requests.get is called directly. @patch lets you replace it during the test without touching the code.

As a decorator — a mock is passed in

from unittest.mock import patch

@patch("app.requests")          # patch requests AS USED IN app.py
def test_user_count(mock_requests):
    mock_requests.get.return_value.json.return_value = ["a", "b", "c"]
    assert get_user_count() == 3
    mock_requests.get.assert_called_once()

The decorator injects the mock as the first extra argument. Stacked decorators inject bottom-up (closest decorator = first argument).

The golden rule: patch where it's USED

# app.py does:  import requests ... requests.get(...)
# ✓ patch the name in app's namespace:
@patch("app.requests")

# ✗ this does NOT work — app already imported its own reference:
@patch("requests.get")     # (sometimes works, often a trap)

If app.py did from requests import get, you'd patch "app.get". Always patch the name as the code under test looks it up.

As a context manager — scoped to a block

def test_user_count_ctx():
    with patch("app.requests") as mock_req:
        mock_req.get.return_value.json.return_value = [1, 2]
        assert get_user_count() == 2

patch.object — patch one attribute

with patch.object(MyClass, "save", return_value=True) as mock_save:
    obj.do_work()
    mock_save.assert_called()

autospec — catch wrong usage

# without autospec, a typo'd call silently "works":
@patch("app.requests")
def test(m):
    m.gett()           # typo — a plain mock happily returns another mock!

# with autospec, the mock matches the real signature:
@patch("app.requests", autospec=True)
def test(m):
    m.gett()           # raises AttributeError — caught!

autospec=True makes the mock enforce the real object's API, catching mistakes a loose mock would hide. Use it when patching something with a known interface.

# report.py
import requests
from datetime import datetime

def daily_report():
    today = datetime.now().strftime("%Y-%m-%d")
    data = requests.get("https://api.example.com/sales").json()
    total = sum(data)
    return f"{today}: ${total}"

# test_report.py
from unittest.mock import patch
from report import daily_report

@patch("report.requests")
@patch("report.datetime")
def test_daily_report(mock_datetime, mock_requests):
    # NOTE arg order: bottom decorator (datetime) is the FIRST arg
    mock_datetime.now.return_value.strftime.return_value = "2026-05-28"
    mock_requests.get.return_value.json.return_value = [10, 20, 30]

    assert daily_report() == "2026-05-28: $60"
    mock_requests.get.assert_called_once()

$ pytest test_report.py -v
test_daily_report PASSED
1 passed     ← deterministic date AND no network call

Read the diff

Two patches: the clock (so "today" is always 2026-05-28) and the network (so sales are always [10,20,30]). Both patched as used in report (report.datetime, report.requests). Watch the decorator-argument order — it's bottom-up, the #1 confusion with stacked @patch. The test is now fully deterministic and offline.

@patch("module.name") swaps an object for a MagicMock during a test and restores it after. Patch where the name is looked up, not where it's defined. Stacked decorators inject bottom-up. Use it as decorator, context manager, or inside a fixture. Add autospec=True to catch wrong usage. Next: putting it together to mock a database.