Pythonのunittest.mock入門|patchで外部APIや時刻を差し替える
天気 API から気温を取ってくる関数をテストしたいのに、テストのたびに本物の API へ通信していませんか。相手が落ちていたり回数制限に引っかかったりすると、コードは正しいのにテストが失敗します。現在時刻や乱数を使う関数も、実行のたびに結果が変わります。
こうした「テストで扱いにくい相手」を、テストの間だけ偽物に差し替えるのが、Python に標準で入っている unittest.mock です。この記事では、Mock の基本、呼ばれ方の確かめ方、patch で urlopen を差し替えて通信なしでテストする方法、最大の落とし穴「使われている場所を patch する」、datetime.now の固定、autospec・mock_open を、Windows 11 の Python 3.12.6 で py -m unittest を実行した結果つきで説明します。
unittest そのものの書き方(TestCase・assertEqual・setUp、py -m unittest の出力の読み方)は「Pythonのテスト入門|unittestとpytestの書き方・実行方法を実例で比較」で説明しているので繰り返しません。出力のファイルの場所は C:\work\ に、ユーザー名は user に置き換えています。
モックとは:テストの間だけ使う替え玉
モック(mock)は、本物の関数やオブジェクトの代わりに置く偽物です。決めておいた値を返し、どんな引数で何回呼ばれたかを記録します。周りの通信や時計を替え玉にして、自分が書いた処理の結果が毎回同じになるようにします。unittest.mock は標準ライブラリなので、インストールは要りません。
| テストしにくい相手 | 困ること | モックで差し替えると |
|---|---|---|
| 外部 API・Web サイト | 通信が遅い・相手が落ちている・回数制限・料金 | 決めた JSON をすぐ返す。通信エラーも再現できる |
| 現在時刻(datetime.now) | 実行する時間で結果が変わる | 「朝 9 時」「夜 21 時」を自由に作れる |
| 乱数(random) | 毎回違う値になる | 「サイコロの 6」を必ず出せる |
| ファイル | テスト用のファイルを用意・削除する手間 | 中身の文字列を渡すだけで読める |
| メール送信・決済など | 本当に送られる・お金が動く | 送らずに「送ろうとした内容」だけ確かめる |
Mock の基本:return_value と side_effect
まずはテストの外で、Mock がどう動くかを見てみます。次の内容を mock_basics.py として保存します。
from unittest.mock import Mock
m = Mock(return_value=42)
print(m("tokyo"))
print(m.called, m.call_count)
print(m.call_args)
m2 = Mock(side_effect=[10, 20, ValueError("3 回目は失敗")])
print(m2())
print(m2())
try:
m2()
except ValueError as e:
print("ValueError:", e)
m3 = Mock()
print(m3.get_user(1).name)
py mock_basics.py
42
True 1
call('tokyo')
10
20
ValueError: 3 回目は失敗
<Mock name='mock.get_user().name' id='2812389328464'>
- return_value:呼ばれたときに返す値。どんな引数で呼んでも 42 が返る
- called・call_count・call_args:呼ばれたか、何回呼ばれたか、最後にどんな引数で呼ばれたか
- side_effect:リストなら呼ばれるたびに順番に返し、例外が入っていればその回は例外を出す。例外を 1 つだけ渡せば毎回その例外、関数を渡せばその関数の結果になる
- Mock は存在しない属性やメソッドも自動で作るので、
m3.get_user(1).nameもエラーにならない
side_effect のリストを使い切ったあとにもう一度呼ぶと StopIteration になります。「1 回目は通信エラー、2 回目は成功」のように、呼ばれる順番で結果を変えたいときに便利です。「何でも自動で作る」性質は、つづり間違いに気づきにくい原因にもなります(あとの autospec で対策します)。
Mock と MagicMock の違い
MagicMock は Mock の子クラスで、__enter__(with 文)や __len__(len)、__iter__(for 文)などの特殊メソッドが最初から用意されています。試すと、with Mock() as x: は TypeError: 'Mock' object does not support the context manager protocol になり、MagicMock は with 文に使えました。patch も特に指定しなければ MagicMock を作るので、通常は MagicMock を使っておけば困りません。with 文のしくみは「Pythonのwith文とは?コンテキストマネージャーの仕組みと作り方」で説明しています。
呼ばれ方を確かめる:assert_called_once_with と call_args_list
モックは呼び出しを記録しているので、「正しい引数で呼ばれたか」を確かめられます。メール送信の関数をモックにして、2 人に送った場面を再現します(history.py)。
from unittest.mock import Mock, call
send = Mock()
for user in ["sato", "suzuki"]:
send(user, subject="お知らせ")
print(send.call_count)
print(send.call_args_list)
print(send.call_args_list == [call("sato", subject="お知らせ"), call("suzuki", subject="お知らせ")])
send.assert_called_once_with("suzuki", subject="お知らせ")
py history.py
2
[call('sato', subject='お知らせ'), call('suzuki', subject='お知らせ')]
True
Traceback (most recent call last):
(途中省略)
AssertionError: Expected 'mock' to be called once. Called 2 times.
Calls: [call('sato', subject='お知らせ'), call('suzuki', subject='お知らせ')].
call_args_list は、呼び出しを順番に並べたリストです。call(...) で同じ形のリストを作れば、== で「この順番で、この引数で呼ばれた」をまとめて比べられます。最後の行は、2 回呼ばれているのに「1 回だけ呼ばれたはず」と確かめたので失敗しました。メッセージに実際の呼び出しの一覧まで出るので、何が違うかがすぐ分かります。
よく使う確認用のメソッドです。条件に合わなければ AssertionError でテストが失敗します。
| メソッド | 確かめること |
|---|---|
| assert_called_once() | ちょうど 1 回呼ばれた |
| assert_called_with(引数) | 最後の呼び出しがこの引数だった |
| assert_called_once_with(引数) | ちょうど 1 回、この引数で呼ばれた |
| assert_any_call(引数) | どこかでこの引数で呼ばれた |
| assert_not_called() | 一度も呼ばれていない |
patch で本物を差し替える:外部 API を通信なしでテスト
ここからが本番です。テストしたいコードの中で使われている関数を、テストの間だけモックに入れ替えるのが patch です。題材は、天気 API から気温を取る weather.py です(api.example.com は説明用の架空の宛先です)。
import json
from urllib.request import urlopen
API_URL = "https://api.example.com/weather?city="
def get_temperature(city):
"""天気 API から気温を取得する"""
with urlopen(API_URL + city, timeout=5) as res:
data = json.load(res)
return data["temp"]
def describe(city):
"""気温を文章にする。通信に失敗したらメッセージを返す"""
try:
temp = get_temperature(city)
except OSError:
return f"{city}: 取得できませんでした"
return f"{city}: {temp}℃"
urlopen の使い方そのものは「PythonでHTTPリクエストを送る方法|urllibとrequestsの使い方と例外処理」で説明しています。通信に失敗したときの URLError は OSError の仲間なので、except OSError で受け止められます。
テストは test_weather.py に書きます。@patch("weather.urlopen") をテストメソッドに付けると、そのテストの間だけ weather モジュールの urlopen が MagicMock に入れ替わり、そのモックが引数(ここでは mock_urlopen)として渡されます。
import io
import unittest
from unittest.mock import patch
from urllib.error import URLError
import weather
class TestWeather(unittest.TestCase):
@patch("weather.urlopen")
def test_get_temperature(self, mock_urlopen):
body = io.BytesIO(b'{"temp": 21.5}')
mock_urlopen.return_value.__enter__.return_value = body
self.assertEqual(weather.get_temperature("tokyo"), 21.5)
mock_urlopen.assert_called_once_with(
"https://api.example.com/weather?city=tokyo", timeout=5
)
def test_describe_error(self):
with patch("weather.urlopen", side_effect=URLError("timed out")):
self.assertEqual(weather.describe("tokyo"), "tokyo: 取得できませんでした")
@patch("weather.urlopen")
@patch("weather.get_temperature", return_value=30)
def test_describe(self, mock_get, mock_urlopen):
self.assertEqual(weather.describe("tokyo"), "tokyo: 30℃")
mock_get.assert_called_once_with("tokyo")
mock_urlopen.assert_not_called()
if __name__ == "__main__":
unittest.main()
1 つ目のテストの mock_urlopen.return_value.__enter__.return_value は「with 文の as res に入るもの」です。そこに read() でバイト列を返す io.BytesIO を置いたので、json.load(res) がそのまま動きます。テスト用の JSON を手で書くときは、JSON整形ツールで構文が正しいか確かめておくと安心です。
py -m unittest test_weather -v
test_describe (test_weather.TestWeather.test_describe) ... ok
test_describe_error (test_weather.TestWeather.test_describe_error) ... ok
test_get_temperature (test_weather.TestWeather.test_get_temperature) ... ok
----------------------------------------------------------------------
Ran 3 tests in 0.001s
OK
3 つとも 0.001 秒ほどで終わりました。通信しようとすると失敗するプロキシ設定にして実行しても成功したので、本物の通信はしていません。
デコレーターと with 文、どちらで書くか
@patch(...) はテストメソッドの間ずっと差し替え、モックは引数で受け取ります。with patch(...) as m: は with ブロックの中だけ差し替え、モックは as の後ろの変数に入ります。どちらも、テストが失敗したり例外が出たりしても、終わったら自動で本物に戻ります。2 つ目のテストのように、side_effect=... などの設定をキーワード引数でまとめて渡すこともできます。デコレーター自体のしくみは「Pythonのデコレーター入門|@の仕組みとfunctools.wrapsを実例で解説」で説明しています。
3 つ目のテストのように @patch を重ねたときは、引数の順番に注意します。公式ドキュメントのとおり、デコレーターは下から適用されるので、いちばん下の @patch のモックが最初の引数(ここでは mock_get)になります。get_temperature ごと差し替えたので、urlopen は一度も呼ばれていません。
最大の落とし穴:「使われている場所」を patch する
先ほど patch("urllib.request.urlopen") ではなく patch("weather.urlopen") と書いた理由を、dice.py で確かめます。
from random import randint
def roll():
"""サイコロを 1 回振る"""
return randint(1, 6)
randint は random モジュールで定義されているので、random.randint を差し替えたくなります。定義元を差し替えるテストと、dice の中の名前を差し替えるテストを並べます(test_dice.py)。
import unittest
from unittest.mock import patch
import dice
class TestDice(unittest.TestCase):
def test_wrong_place(self):
with patch("random.randint", return_value=6) as mock_randint:
dice.roll()
mock_randint.assert_called_once_with(1, 6)
def test_right_place(self):
with patch("dice.randint", return_value=6) as mock_randint:
self.assertEqual(dice.roll(), 6)
mock_randint.assert_called_once_with(1, 6)
if __name__ == "__main__":
unittest.main()
py -m unittest test_dice
.F
======================================================================
FAIL: test_wrong_place (test_dice.TestDice.test_wrong_place)
----------------------------------------------------------------------
Traceback (most recent call last):
File "C:\work\test_dice.py", line 12, in test_wrong_place
mock_randint.assert_called_once_with(1, 6)
(途中省略)
AssertionError: Expected 'randint' to be called once. Called 0 times.
----------------------------------------------------------------------
Ran 2 tests in 0.001s
FAILED (failures=1)
定義元を差し替えたほうは Called 0 times(一度も呼ばれていない)で失敗しました。dice.roll() はモックではなく、本物の randint を呼んでいたのです。
理由は、from random import randint が「dice モジュールの中に randint という名前を作り、その時点の本物の関数を指させる」命令だからです。あとで patch が random.randint という名前をモックに付け替えても、dice の中の名前は本物を指したままです。roll() は dice の中の名前で randint を探すので、本物が呼ばれます。

実際に patch("random.randint") の中で dice.randint is mock_randint を表示すると False、patch("dice.randint") の中では True になりました。
公式ドキュメントの「Where to patch」にも、オブジェクトが定義された場所ではなく、探される(使われる)場所を patch するのが基本だと書かれています。覚え方は次のとおりです。
| テストされる側の import の書き方 | 使い方 | patch に書く名前 |
|---|---|---|
| from random import randint | randint(1, 6) | “dice.randint” |
| import random | random.randint(1, 6) | “random.randint” |
| from urllib.request import urlopen | urlopen(url) | “weather.urlopen” |
| import urllib.request | urllib.request.urlopen(url) | “urllib.request.urlopen” |
つまり、テストされる側のコードで呼び出しに書かれている名前(randint なのか random.randint なのか)を、その名前があるモジュールから指定します。外部 API のテストで間違えると本物の通信が発生します。assert_called_once_with などで「モックが本当に呼ばれたか」まで確かめれば気づけます。
現在時刻を固定する:datetime.now は直接 patch できない
時間帯であいさつを変える関数を考えます。テストのたびに時刻が変わるので、時刻を固定したいところです。まず素直に datetime.datetime.now を差し替えてみます。
from unittest.mock import patch
from datetime import datetime
with patch("datetime.datetime.now", return_value=datetime(2026, 1, 1, 9, 0)):
pass
Traceback (most recent call last):
File "C:\Users\user\AppData\Local\Programs\Python\Python312\Lib\unittest\mock.py", line 1574, in __enter__
setattr(self.target, self.attribute, new_attr)
TypeError: cannot set 'now' attribute of immutable type 'datetime.datetime'
(以下、後片付けで同じ TypeError がもう一度出るので省略)
「変更できない型(immutable type)の now 属性は設定できない」という TypeError になりました。datetime は C 言語で書かれた組み込みの型で、属性を書き換えられないためです。公式ドキュメントの unittest.mock-examples(Partial mocking)にも、C で書かれた datetime.date の today() はそのまま差し替えられないと書かれています。
対策は、小さなラッパー関数を作ってそれを patch するか、時刻を引数で受け取る設計にすることです。greet.py は両方に対応させました。
from datetime import datetime
def current_time():
"""現在時刻を返す(テストで差し替えるための小さな関数)"""
return datetime.now()
def greeting(when=None):
"""時刻に合わせたあいさつ。when を省略すると現在時刻を使う"""
if when is None:
when = current_time()
if 5 <= when.hour < 12:
return "おはようございます"
if when.hour < 18:
return "こんにちは"
return "こんばんは"
import unittest
from datetime import datetime
from unittest.mock import patch
import greet
class TestGreeting(unittest.TestCase):
@patch("greet.current_time", return_value=datetime(2026, 1, 1, 9, 0))
def test_morning(self, mock_now):
self.assertEqual(greet.greeting(), "おはようございます")
@patch("greet.current_time", return_value=datetime(2026, 1, 1, 21, 30))
def test_night(self, mock_now):
self.assertEqual(greet.greeting(), "こんばんは")
def test_noon_by_argument(self):
self.assertEqual(greet.greeting(datetime(2026, 1, 1, 12, 0)), "こんにちは")
if __name__ == "__main__":
unittest.main()
3 つとも成功しました。current_time() は自分のモジュールの普通の関数なので、patch("greet.current_time") で差し替えられます。引数で渡す 3 つ目のテストは、モックそのものが要りません。
もう 1 つ、公式ドキュメントの例と同じく patch("greet.datetime") でモジュールの中の datetime という名前ごと差し替え、now.return_value を設定する方法もあります(15 時で動作を確認)。ただし、その間は greet の中で日時を作るコードにもモックが返ります。迷ったら引数で渡す設計がいちばんシンプルです。日時の扱いは「Pythonのdatetimeの使い方|日時の計算・タイムゾーン・Unix時間を実例で解説」で説明しています。
autospec=True で引数の間違いを見つける
Mock は何でも受け入れるので、本物の関数では受け付けない呼び方をしてもエラーになりません。たとえば get_temperature(city) は引数が 1 つなのに、2 つ渡してみます。
from unittest.mock import patch
import weather
with patch("weather.get_temperature") as mock_get:
mock_get("tokyo", "celsius")
print("autospec なし: エラーにならない")
with patch("weather.get_temperature", autospec=True) as mock_get:
mock_get("tokyo", "celsius")
autospec なし: エラーにならない
Traceback (most recent call last):
(途中省略)
TypeError: too many positional arguments
autospec=True を付けると、本物の関数と同じ引数の形をもつモックが作られ、合わない呼び方は TypeError(位置引数が多すぎる)になります。関数の引数を変えたのに呼び出し側を直し忘れた、という間違いもテストで見つかります。公式ドキュメントでも、多くの場合は既存の patch に autospec=True を足すだけで、つづり間違いや API の変更によるバグから守られると説明されています(__init__ の中で作られる属性は見えないなどの制限があるため、初期設定ではありません)。
mock_open でファイル読み込みを差し替える
mock_open を使うと、ファイルを作らずに中身の文字列だけでテストできます。題材は名前の一覧を読む names.py です。
def load_names(path):
"""1 行に 1 人の名前が書かれたファイルを読み、空行を除いたリストを返す"""
with open(path, encoding="utf-8") as f:
return [line.strip() for line in f if line.strip()]
import unittest
from unittest.mock import mock_open, patch
from names import load_names
class TestLoadNames(unittest.TestCase):
def test_load_names(self):
m = mock_open(read_data="山田\n\n佐藤\n")
with patch("names.open", m):
self.assertEqual(load_names("members.txt"), ["山田", "佐藤"])
m.assert_called_once_with("members.txt", encoding="utf-8")
if __name__ == "__main__":
unittest.main()
read_data に渡した文字列が、read()・readline()・readlines()、それに for 文での 1 行ずつの読み込み(Python 3.8 から対応)で返されます。members.txt は存在しませんが、テストは成功しました。assert_called_once_with で encoding="utf-8" を付けて開いているかまで確かめられるのも利点です。
ここでも「使われている場所」のルールどおり、names モジュールの中の open を差し替えています(組み込み関数の差し替えは、Python 3.5 から create=True なしで扱えます)。書き込みや複雑なファイル操作は、mock_open より一時ファイル(tempfile や pytest の tmp_path)を使うほうが本物に近いテストになります。open の使い方は「Pythonのファイル読み書き|open・with・encoding指定と文字化けの直し方」で説明しています。
ここまでの 4 つのテストファイル(dice は正しいほうだけ)をまとめて py -m unittest すると、Ran 8 tests in 0.002s・OK でした。何度実行しても同じ結果になります。
よくある間違い
assert のつづりを間違える(assret_called_once など)
Mock は存在しない属性も自動で作るので、昔は m.assret_called_once() のようにつづりを間違えると、何も確かめずにテストが成功してしまいました(公式ドキュメントでは 3.5 より前の動き)。今のドキュメントには、assert・assret・asert・aseert・assrt で始まる名前の属性に触れると AttributeError になると書かれています。3.12.6 で試した結果です。
assret_called_once -> 'assret_called_once' is not a valid assertion. Use a spec for the mock if 'assret_called_once' is meant to be an attribute.
called_once_with -> 'called_once_with' is not a valid assertion. Use a spec for the mock if 'called_once_with' is meant to be an attribute.
この PC の 3.12.6 では、assert_ を付け忘れた called_once_with も AttributeError になりました。ただし、すべての書き間違いが検出されるわけではなく、古い Python では動きが違う場合があります。確認用のメソッドは表の名前をコピーして使い、わざと失敗させて、テストが本当に失敗するかを一度見ておくと確実です。
patch に書く名前を間違える
patch("weather.urlopn")(つづり間違い)は AttributeError: ... does not have the attribute 'urlopn'、モジュール名のない patch("urlopen") は TypeError: Need a valid target to patch. になりました。必ず「モジュール名.名前」で書きます。エラーが出ないぶん怖いのは、先ほどの「定義元を patch する」間違いです。
モックしすぎて、何もテストしていない
テストしたい関数の中身までモックにすると、「モックに 30 を返させたら 30 が返ってきた」という、自分で決めた値を確かめるだけのテストになります。差し替えるのは外側との境目(通信・時刻・乱数・ファイル・メール送信など)だけにし、自分で書いた計算や変換はモックにしません。戻り値や結果も assertEqual で確かめ、モックが返す値は本物の API の形に合わせます(ずれていると、テストは通るのに本番で壊れます)。モックの準備が長くなるときは、テストしやすい設計に直すほうが早いことが多いです。
まとめ
unittest.mock を使うと、通信・時刻・乱数・ファイルに頼る処理も、速く、毎回同じ結果でテストできます。値は return_value と side_effect で決め、呼ばれ方は assert_called_once_with や call_args_list で確かめます。patch は「定義元」ではなく使われている場所に書き、autospec=True で引数の間違いも拾えるようにしておくと安心です。
関連する記事・ツール
- Pythonのテスト入門|unittestとpytestの書き方・実行方法を実例で比較
- PythonでHTTPリクエストを送る方法|urllibとrequestsの使い方と例外処理
- Pythonのdatetimeの使い方|日時の計算・タイムゾーン・Unix時間を実例で解説
- Pythonのデコレーター入門|@の仕組みとfunctools.wrapsを実例で解説
- Pythonのwith文とは?コンテキストマネージャーの仕組みと作り方
- Pythonのrandomとsecretsの違い|安全な乱数でパスワード・トークンを作る
- JSON整形ツール