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は使えません。


あわせて読みたい

対面・無料|東京・永田町で毎週土曜日13時

この記事のようなコードを、講師に聞きながら動かしてみる

ゼロからはじめるPython入門講座

8年間・累計600回開催/これまで全国で2万人以上が参加

「やはり対面で聞けるのはとても気づきがあり、価値があると思います」

参加者の声

  • 本当に初心者からの講座です。プログラミングに触ったことがなくて大丈夫です
  • 対面だから、その場で聞けます。つまずいた所を持ち帰らずに解決できます
  • 講座は1時間。そのあとも残って学習を続けられ、講師にも質問できます
  • 独学で挫折した方も。糸口が見つかって、講座のあと会員になる方が多くいます

無料で参加する|開催日程を見る

参加費は無料です