Python unittest.TestCaseとは?書き方・実行方法・仕組みとpytestとの違い
unittest.TestCaseは、Python標準のテスト用クラスです。これを継承したクラスにtest_で始まるメソッドを書き、中でself.assertEqual()などを呼ぶと、python3 -m unittestで自動的に実行・判定されます。
この記事は、TestCaseクラスそのものに絞って、書き方、実行結果の読み方、「テストごとにインスタンスが作られる」という動き方、setUpClass・subTest・skip・assertLogsなどのよく使う機能、pytestから実行する方法までを説明します。コードはすべてPython 3.12.15で実行し、出力をそのまま載せています(pytestは9.1.1)。unittest全体の入門はPythonのunittestの使い方、ユニットテストの考え方から知りたい方はPythonのユニットテスト(単体テスト)入門をご覧ください。
unittest.TestCaseの基本の書き方
テストする関数をcalc.pyに用意します。
def add(a, b):
return a + b
def divide(a, b):
return a / b
テストはtest_calc.pyに書きます。unittest.TestCaseを継承したクラスを作り、確かめたいことを1つずつtest_メソッドにします。説明のため、わざと失敗するテストとエラーになるテストも入れています。
import unittest
from calc import add, divide
class TestCalc(unittest.TestCase):
def test_add(self):
self.assertEqual(add(1, 2), 3)
def test_add_wrong(self):
self.assertEqual(add(1, 2), 4) # わざと失敗させる
def test_divide_by_zero(self):
self.assertRaises(ZeroDivisionError, divide, 1, 0)
def test_broken(self):
divide(1, "a") # テスト自体が例外で止まる
if __name__ == "__main__":
unittest.main()
実行結果(python3 test_calc.py、ファイルパスは省略):
.FE.
======================================================================
ERROR: test_broken (__main__.TestCalc.test_broken)
----------------------------------------------------------------------
Traceback (most recent call last):
File ".../test_calc.py", line 16, in test_broken
divide(1, "a") # テスト自体が例外で止まる
^^^^^^^^^^^^^^
File ".../calc.py", line 5, in divide
return a / b
~~^~~
TypeError: unsupported operand type(s) for /: 'int' and 'str'
======================================================================
FAIL: test_add_wrong (__main__.TestCalc.test_add_wrong)
----------------------------------------------------------------------
Traceback (most recent call last):
File ".../test_calc.py", line 10, in test_add_wrong
self.assertEqual(add(1, 2), 4) # わざと失敗させる
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 3 != 4
----------------------------------------------------------------------
Ran 4 tests in 0.000s
FAILED (failures=1, errors=1)
結果の記号の読み方(FAILとERRORの違い)
| 記号 | 意味 | まず疑うところ |
|---|---|---|
. |
成功 | - |
F(FAIL) |
assertの条件が成り立たなかった | テスト対象のコード、または期待値 |
E(ERROR) |
assert以外の例外でテストが止まった | テストコード自体の書き間違いや準備不足 |
s |
スキップ | スキップの条件 |
x / u |
想定どおりの失敗(expectedFailure)/想定外の成功 | expectedFailureを付けたテスト |
1行目の.FE.は「成功・失敗・エラー・成功」の意味です。例外が出ることを確かめたいときは、test_divide_by_zeroのようにassertRaises()を使えばFAILでもERRORでもなく成功になります(assertRaises()の解説)。
テストの実行方法
python3 test_calc.py # ファイル末尾の unittest.main() で実行
python3 -m unittest # カレント以下の test*.py を自動で探して実行
python3 -m unittest test_calc # モジュールを指定
python3 -m unittest test_calc.TestCalc.test_add # 1つのテストだけ
python3 -m unittest -v # 1件ずつ結果を表示
python3 -m unittest -k add # 名前に add を含むテストだけ
python3 -m unittest --durations 5 # 遅いテスト上位5件を表示(Python 3.12以降)
--durationsはPython 3.12で追加されたオプションです(unittest公式ドキュメント(2026年10月18日確認))。テストが1件も見つからなかった場合は「NO TESTS RAN」と表示され、終了コードは5になります。
$ python3 -m unittest
----------------------------------------------------------------------
Ran 0 tests in 0.000s
NO TESTS RAN
$ echo $?
5
CIで「テストが0件なのに成功扱い」になるのを防げます。0件になる原因の多くは、ファイル名がtestで始まっていない、メソッド名がtestで始まっていない、テストのあるフォルダに__init__.pyが無い、のどれかです。
TestCaseの仕組み:テスト1件ごとにインスタンスが作られる
TestCaseを理解するうえで一番大事なのは、test_メソッド1つにつき、TestCaseのインスタンスが1つ作られるという点です。公式ドキュメントにも「TestCaseの各インスタンスは1つのメソッドだけを実行する」と書かれています。
import unittest
class TestInstance(unittest.TestCase):
created = []
def setUp(self):
TestInstance.created.append(id(self))
self.items = [] # テストごとに新しいリスト
def test_a(self):
self.items.append("a")
self.assertEqual(self.items, ["a"])
def test_b(self):
self.items.append("b")
self.assertEqual(self.items, ["b"]) # test_a の "a" は残っていない
@classmethod
def tearDownClass(cls):
print("作られたインスタンスの数:", len(set(cls.created)))
if __name__ == "__main__":
unittest.main(verbosity=2)
実行結果:
test_a (__main__.TestInstance.test_a) ... ok
test_b (__main__.TestInstance.test_b) ... ok
----------------------------------------------------------------------
Ran 2 tests in 0.000s
OK
作られたインスタンスの数: 2
テストが2件なので、インスタンスも2つ作られています。そのため、test_aでselfに入れた値はtest_bからは見えません。テスト同士を独立させるための仕組みですが、「前のテストで作ったデータを次のテストで使う」書き方はできない、ということでもあります。共通の準備はsetUp()(テストごと)かsetUpClass()(クラスで1回)に書きます(setUp・tearDownの使い方)。
実行されるのは「test」で始まるメソッドだけ、順番は名前順
import unittest
class TestOrder(unittest.TestCase):
def test_c(self): pass
def test_a(self): pass
def test_b(self): pass
def check_x(self): self.fail("test_ で始まらないので実行されない")
if __name__ == "__main__":
unittest.main(verbosity=2)
実行結果:
test_a (__main__.TestOrder.test_a) ... ok
test_b (__main__.TestOrder.test_b) ... ok
test_c (__main__.TestOrder.test_c) ... ok
----------------------------------------------------------------------
Ran 3 tests in 0.000s
OK
書いた順(c・a・b)ではなく、名前の順(a・b・c)に実行されています。またcheck_xはtestで始まらないので実行されていません。「テストを書いたのに件数に入らない」ときは、まずメソッド名を確認してください。
TestCaseのよく使う機能
TestCaseには、assert系メソッドのほかにも便利な機能が用意されています。主なものを1つのテストクラスにまとめました。
import logging
import sys
import unittest
class TestFeatures(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls.config = {"rate": 0.1} # クラスで1回だけ用意する重い準備
def test_float(self):
self.assertAlmostEqual(0.1 + 0.2, 0.3)
def test_subtest(self):
for n in [2, 4, 5]:
with self.subTest(n=n):
self.assertEqual(n % 2, 0)
@unittest.skipIf(sys.platform == "darwin", "macOSでは実行しない")
def test_linux_only(self):
pass
def test_logs(self):
with self.assertLogs("app", level="WARNING") as cm:
logging.getLogger("app").warning("在庫が少なくなっています")
self.assertEqual(cm.output, ["WARNING:app:在庫が少なくなっています"])
if __name__ == "__main__":
unittest.main(verbosity=2)
実行結果(macOSで実行、ファイルパスは省略):
test_float (__main__.TestFeatures.test_float) ... ok
test_linux_only (__main__.TestFeatures.test_linux_only) ... skipped 'macOSでは実行しない'
test_logs (__main__.TestFeatures.test_logs) ... ok
test_subtest (__main__.TestFeatures.test_subtest) ...
test_subtest (__main__.TestFeatures.test_subtest) (n=5) ... FAIL
======================================================================
FAIL: test_subtest (__main__.TestFeatures.test_subtest) (n=5)
----------------------------------------------------------------------
Traceback (most recent call last):
File ".../test_features.py", line 17, in test_subtest
self.assertEqual(n % 2, 0)
AssertionError: 1 != 0
----------------------------------------------------------------------
Ran 4 tests in 0.001s
FAILED (failures=1, skipped=1)
| 機能 | 何に使うか |
|---|---|
setUpClass()(classmethod) |
クラスの全テストの前に1回だけ準備する(DB接続など重い準備) |
assertAlmostEqual() |
小数の比較。0.1 + 0.2は0.3とぴったり一致しないため、assertEqualではなくこちらを使う |
subTest() |
ループで複数の値を試し、どの値で失敗したかを表示する(上の例ではn=5) |
@unittest.skipIf()/skipTest() |
OSやライブラリの有無などの条件でテストを飛ばす |
assertLogs()/assertNoLogs() |
ログが出る(出ない)ことを確かめる。assertNoLogsはPython 3.10以降 |
addCleanup()/enterContext() |
後片付けを登録する。enterContextはPython 3.11以降 |
assert系メソッドの使い分けはassertEqualとassert系メソッドの使い分け、subTestの詳しい使い方はsubTest()の使い方で解説しています。
素のassert文ではなくself.assertXxx()を使う理由
TestCaseの中でassert 1 == 2と書いても失敗は検出されますが、メッセージはAssertionErrorだけで、何と何が違ったのかが表示されません。self.assertEqual(1, 2)ならAssertionError: 1 != 2と両方の値が出ます。また、python3 -Oで実行するとassert文そのものが無効になります。unittestで書くならassert系メソッドを使いましょう。
テストメソッドでreturnしない
公式ドキュメントでは、テストメソッドがNone以外の値を返すことはPython 3.11から非推奨とされています(2026年10月18日確認)。テストの結果はreturnではなく、assert系メソッドで判定します。
非同期関数をテストするIsolatedAsyncioTestCase
async defの関数をテストするときは、TestCaseの代わりにunittest.IsolatedAsyncioTestCase(Python 3.8以降)を継承すると、テストメソッド自体をasync defで書けます。
import asyncio
import unittest
async def fetch_price():
# 重い処理を別スレッドで実行して結果を待つ例
return await asyncio.to_thread(int, "1200")
class TestAsync(unittest.IsolatedAsyncioTestCase):
async def test_fetch_price(self):
self.assertEqual(await fetch_price(), 1200)
if __name__ == "__main__":
unittest.main()
実行結果:
.
----------------------------------------------------------------------
Ran 1 test in 0.004s
OK
unittest.TestCaseとpytestの違いと併用
「unittest testcase vs pytest」もよく検索されます。主な違いは次のとおりです。
| 項目 | unittest.TestCase | pytest |
|---|---|---|
| インストール | 不要(標準ライブラリ) | pipで入れる |
| テストの書き方 | クラスを継承し、メソッドで書く | 関数だけで書ける(クラスも可) |
| 判定 | self.assertEqual() など | 素のassert文(失敗時に値を詳しく表示) |
| 準備と後片付け | setUp・tearDown・setUpClass | fixture |
| 同じテストを値を変えて実行 | subTest() | @pytest.mark.parametrize |
どちらか一方を選ぶ必要はありません。pytestの公式ドキュメントによると、pytestはunittest.TestCaseのサブクラスをそのまま収集して実行でき、setUp・tearDown・setUpClass・skip系デコレーター・subTest(pytest 9.0以降)にも対応しています。一方、TestCaseのクラスの中ではpytestのfixture(autouseを除く)やparametrizeは使えないと明記されています(How to use unittest-based tests with pytest(2026年10月18日確認))。
上のtest_features.pyとtest_instance.pyをpytest 9.1.1で実行した結果の最後の部分です。
=========================== short test summary info ============================
SUBFAILED(n=5) test_features.py::TestFeatures::test_subtest - AssertionError:...
1 failed, 5 passed, 1 skipped, 2 subtests passed in 0.01s
unittestで書いた既存のテストはそのまま残し、新しいテストからpytestの書き方にしていく、という移り方ができます。pytestの使い方はpytestの使い方入門をご覧ください。
unittest.TestCaseのポイントまとめ
unittest.TestCaseを継承し、testで始まるメソッドにテストを書く- 判定は
self.assertEqual()などのassert系メソッドで行う - FAILは「期待と違った」、ERRORは「テストが例外で止まった」
- テスト1件ごとに新しいインスタンスが作られ、実行は名前順。テスト同士の順番に頼らない
- 準備はsetUp/setUpClass、値を変えた繰り返しはsubTest、条件付きの除外はskipIf
- 非同期関数はIsolatedAsyncioTestCase、pytestからもそのまま実行できる
テストの書き方は、実際にコードを書きながら身につけるのが近道です。通学型プログラミングスクールのテックジムでは、自分のペースで課題を進めながら、分からないところをトレーナーに質問できます。まずは無料Python講座などの無料講座の一覧から試せます。
よくある質問
Q. unittest.TestCaseとは何ですか?
Python標準ライブラリunittestのテスト用クラスです。これを継承したクラスにtestで始まるメソッドを書き、self.assertEqual()などで結果を判定します。python3 -m unittestで自動的に探して実行されます。
Q. テストを書いたのに実行されないのはなぜですか?
メソッド名がtestで始まっていない、ファイル名がtestで始まっていない、テストを置いたフォルダに__init__.pyが無い、のいずれかが多い原因です。1件も見つからないとNO TESTS RANと表示され、終了コードは5になります。
Q. test_aでselfに入れた値をtest_bで使えないのはなぜですか?
TestCaseはテストメソッド1つごとに新しいインスタンスを作って実行するためです。テスト同士を独立させるための仕組みなので、共通の準備はsetUp()かsetUpClass()に書きます。
Q. unittest.TestCaseで書いたテストはpytestで実行できますか?
実行できます。pytestはTestCaseのサブクラスを自動で収集し、setUp・tearDown・setUpClass・skip系デコレーター・subTestにも対応しています。ただしTestCaseのクラスの中ではpytestのfixture(autouseを除く)とparametrizeは使えません。
あわせて読みたい
- Python unittestのassertEqualとは?assert系メソッドの使い分け
- Python unittestのsetUp・tearDownの使い方|setUpClass・addCleanupとの違いとpytestでの書き方
- Python assertRaises()とは?例外が出ることをテストする方法
- Pythonのunittestの使い方|テストコードの書き方・実行コマンド・assertEqualなど主なメソッド
- ユニットテスト(単体テスト)とは?意味・書き方と言語別フレームワーク|pytestの実行例つき
- Python unittest クラス一覧|TestCase・TestSuite・TestLoaderなど




