Pythonのテスト入門|unittestとpytestの書き方・実行方法を実例で比較
関数を書いたあと、毎回 print() で結果を目で確かめていませんか。テストは、その確認をプログラムにしておくものです。一度書いておけば、コードを直すたびにコマンド 1 つで「前と同じように動くか」を確かめられます。
この記事では、消費税込みの金額を計算する関数と、名前の空白を整える関数を題材に、Python に標準で入っている unittest と、広く使われている pytest を、Windows 11 の Python 3.12・pytest 9.1.1 で実際に動かした結果つきで比べます。失敗したときの出力の読み方、テストファイルの名前の付け方、よくある間違いも紹介します。
出力に出るファイルの場所は、読みやすいように C:\work\ に置き換えて載せています(ユーザー名は user にしています)。
テストとは:期待する結果をコードで書いておくこと
題材にするのは、次の price.py です。税抜きの金額から税込みの金額を求める関数(1 円未満は切り捨て)と、名前の前後の空白を取り、間の空白(全角を含む)を半角 1 つにそろえる関数です。
def price_with_tax(price, rate=10):
"""税抜きの金額から税込みの金額を求める(1 円未満は切り捨て)"""
if price < 0:
raise ValueError("金額は 0 以上にしてください")
return price * (100 + rate) // 100
def format_name(name):
"""前後の空白を取り、間の空白(全角を含む)を半角 1 つにそろえる"""
return " ".join(name.split())
テストでは、「この入力なら、この結果になるはず」という組み合わせを書きます。たとえば次のようなものです。
| 呼び出し | 期待する結果 | 確かめたいこと |
|---|---|---|
| price_with_tax(1000) | 1100 | 標準の税率 10% |
| price_with_tax(99) | 108 | 108.9 円の端数を切り捨てる |
| price_with_tax(-1) | ValueError | マイナスの金額はエラーにする |
| format_name(” 山田 太郎 “) | “山田 太郎” | 全角の空白もそろえる |
一度書いておけば、直したときに壊していないかがすぐ分かります。あとで「四捨五入のほうが読みやすい」と書き換えても、99 円の行が失敗して、切り捨てのルールを壊したことに気づけます。境目の値(0、端数が出る値、マイナス)を毎回手で試す必要もなくなり、テストそのものが関数の使い方の見本にもなります。
unittest の基本:標準ライブラリだけで書く
unittest は Python に最初から入っているので、インストールは要りません。price.py と同じフォルダーに test_price_unittest.py を作ります。
import unittest
from price import format_name, price_with_tax
class TestPriceWithTax(unittest.TestCase):
def test_standard_rate(self):
self.assertEqual(price_with_tax(1000), 1100)
def test_reduced_rate(self):
self.assertEqual(price_with_tax(1000, rate=8), 1080)
def test_round_down(self):
self.assertEqual(price_with_tax(99), 108)
def test_negative_price(self):
with self.assertRaises(ValueError):
price_with_tax(-1)
class TestFormatName(unittest.TestCase):
def test_spaces(self):
self.assertEqual(format_name(" 山田 太郎 "), "山田 太郎")
if __name__ == "__main__":
unittest.main()
unittest.TestCaseを継承したクラスを作り、その中にテストをメソッドとして書く- メソッド名は test で始める。Python の公式ドキュメントにも、名前が test で始まるメソッドがテストとして扱われると書かれています
self.assertEqual(結果, 期待値)で、2 つが等しいかを確かめるwith self.assertRaises(ValueError):の中で、例外が出ることを確かめる。例外が出なければ失敗、別の種類の例外ならエラーになる
ファイルのあるフォルダーで、次のコマンドを実行します。
py -m unittest
.....
----------------------------------------------------------------------
Ran 5 tests in 0.000s
OK
1 行目の . は、テスト 1 つが成功したしるしです。5 つとも成功したので、最後に OK と出ます。引数なしの python -m unittest は python -m unittest discover と同じで、今いるフォルダーから test*.py という名前のファイルを探して実行します。
-v を付けると、test_round_down (test_price_unittest.TestPriceWithTax.test_round_down) ... ok のように、テストごとの結果が 1 行ずつ出ます。
py -m unittest -v
このとき、テストは書いた順ではなく名前の順に実行されました。テストは、どの順番で動いても同じ結果になるように書くのが基本です。
1 つだけ動かすときは py -m unittest test_price_unittest.TestPriceWithTax.test_round_down のように「ファイル名.クラス名.メソッド名」で指定します。名前の一部で絞り込む -k、最初の失敗で止める -f(–failfast)も使えます。
setUp と tearDown:テストごとの準備と後片付け
price.py に、1 行に 1 つ金額が書かれたファイルを読んで税込みの合計を返す関数を足し、テストのたびに一時ファイルを用意します。
def total_from_file(path):
"""1 行に 1 つ税抜きの金額が書かれたファイルを読み、税込みの合計を返す"""
with open(path, encoding="utf-8") as f:
total = sum(int(line) for line in f if line.strip())
return price_with_tax(total)
setUp() は各テストの前に、tearDown() は各テストの後に、自動で呼ばれます。setUp が成功していれば、テストが失敗しても tearDown は実行されます。
import os
import tempfile
import unittest
from price import total_from_file
class TestTotalFromFile(unittest.TestCase):
def setUp(self):
self.tmpdir = tempfile.TemporaryDirectory()
self.path = os.path.join(self.tmpdir.name, "prices.txt")
def tearDown(self):
self.tmpdir.cleanup()
def test_total(self):
with open(self.path, "w", encoding="utf-8") as f:
f.write("100\n200\n\n300\n")
self.assertEqual(total_from_file(self.path), 660)
テストごとに別の一時フォルダーで動くので、テストどうしが影響し合いません。ファイルの読み書きと encoding の指定は「Pythonのファイル読み書き」で解説しています。
pytest の基本:assert だけで書ける
pytest は標準ライブラリではないので、pip でインストールします。プロジェクトごとに仮想環境(venv)を作り、その中に入れるのがおすすめです。PowerShell で、プロジェクトのフォルダーに移動してから 1 行ずつ実行します。
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install pytest
Activate.ps1 が実行ポリシーのエラーで止まるときや、venv の詳しい使い方は「Pythonの仮想環境venvの使い方」を、pip については「pipの使い方」を見てください。この記事では 2026 年 10 月にインストールした pytest 9.1.1 で確かめています。
同じテストを pytest で書くと、こうなります。ファイル名は test_price.py です。
import pytest
from price import format_name, price_with_tax
def test_standard_rate():
assert price_with_tax(1000) == 1100
def test_round_down():
assert price_with_tax(99) == 108
def test_negative_price():
with pytest.raises(ValueError, match="0 以上"):
price_with_tax(-1)
def test_format_name():
assert format_name(" 山田 太郎 ") == "山田 太郎"
クラスも self も要らず、test_ で始まる関数の中に、ふつうの assert 文を書くだけです。pytest.raises の match には正規表現を書き、例外のメッセージを re.search() で調べます(「0 以上」という文字が入っていれば合格)。
python -m pytest
collected 11 items
test_file_unittest.py .. [ 18%]
test_price.py .... [ 54%]
test_price_unittest.py ..... [100%]
============================= 11 passed in 0.03s ==============================
pytest は unittest で書いたテストもそのまま実行できます。上の結果では、unittest 版の 7 つと pytest 版の 4 つを、まとめて 11 個実行しています。
失敗したテストの出力の読み方
テストが役に立つのは、失敗したときです。price.py の 2 つの関数を、わざと次のように書き換えてみます。
def price_with_tax(price, rate=10):
if price < 0:
raise ValueError("金額は 0 以上にしてください")
return round(price * (100 + rate) / 100) # 切り捨てではなく四捨五入になってしまった
def format_name(name):
return name.strip().replace(" ", " ") # 半角 2 つしか直さない
unittest の場合
F..F.
======================================================================
FAIL: test_spaces (test_price_unittest.TestFormatName.test_spaces)
----------------------------------------------------------------------
Traceback (most recent call last):
File "C:\work\test_price_unittest.py", line 23, in test_spaces
self.assertEqual(format_name(" 山田 太郎 "), "山田 太郎")
AssertionError: '山田\u3000\u3000太郎' != '山田 太郎'
- 山田 太郎
? ^^
+ 山田 太郎
? ^
======================================================================
FAIL: test_round_down (test_price_unittest.TestPriceWithTax.test_round_down)
----------------------------------------------------------------------
Traceback (most recent call last):
File "C:\work\test_price_unittest.py", line 14, in test_round_down
self.assertEqual(price_with_tax(99), 108)
AssertionError: 109 != 108
----------------------------------------------------------------------
Ran 5 tests in 0.001s
FAILED (failures=2)
- 1 行目:
Fが失敗、.が成功。テストの途中で予期しない例外が出たものはE(エラー)になり、トレースバックが出る(読み方は「Pythonの例外処理入門」) - FAIL: の行:失敗したテストの名前(メソッド名・ファイル名.クラス名)
- File の行:失敗した assert の場所(test_price_unittest.py の 14 行目)
- AssertionError の行:
実際の結果 != 期待値。assertEqual(結果, 期待値) の順に書いたので、左が実際の値。99 円が 109 円になっている - 文字列の場合は、
-(第 1 引数)と+(第 2 引数)の行が並び、?の行の^が違う文字を指す
名前のテストでは、見た目ではどちらも空白に見えますが、'山田\u3000\u3000太郎' の表示で、全角の空白(U+3000)が残っていると分かります。
pytest の場合
test_price.py .F.F [100%]
================================== FAILURES ===================================
_______________________________ test_round_down _______________________________
def test_round_down():
> assert price_with_tax(99) == 108
E assert 109 == 108
E + where 109 = price_with_tax(99)
test_price.py:11: AssertionError
______________________________ test_format_name _______________________________
def test_format_name():
> assert format_name(" 山田 太郎 ") == "山田 太郎"
E AssertionError: assert '山田\u3000\u3000太郎' == '山田 太郎'
E
E - 山田 太郎
E + 山田 太郎
test_price.py:20: AssertionError
=========================== short test summary info ===========================
FAILED test_price.py::test_round_down - assert 109 == 108
FAILED test_price.py::test_format_name - AssertionError: assert '山田\u3000\u...
========================= 2 failed, 2 passed in 0.04s =========================
>の行が失敗した assert、Eの行がその理由where 109 = price_with_tax(99)のように、式の途中の値まで表示してくれる。ふつうの assert 文なのに中身が分かるのは、pytest が assert 文を書き換えて情報を集めているため- 文字列の差分は、この実行では
-が == の右側(期待値)、+が左側(実際の結果)。unittest とは記号の向きが違うので、記号よりも中身で判断するとよい - 最後の short test summary info に、失敗したテストが 1 行ずつまとまる。ここをまず見て、上の詳しい表示へ戻るのが早い
リストの比較では、どこが違うかも教えてくれます。assert [100, 200, 300] == [100, 250, 300] は At index 1 diff: 200 != 250(1 番目が違う)と表示され、長い差分は省略されて use '-vv' to show と出ます。全部見たいときは -vv を付けます。長い文章どうしの違いを目で探したいときは、テキスト差分比較ツールに貼ると、違う部分が色分けで分かります。
pytest でよく使う書き方
parametrize:入力と期待値の表でテストする
同じ形のテストを何個も書く代わりに、@pytest.mark.parametrize で入力と期待値を並べられます。test_price.py の最後に追加します。
@pytest.mark.parametrize(
"price, rate, expected",
[
(1000, 10, 1100),
(1000, 8, 1080),
(99, 10, 108),
(0, 10, 0),
],
)
def test_price_with_tax(price, rate, expected):
assert price_with_tax(price, rate) == expected
test_price.py::test_price_with_tax[1000-10-1100] PASSED [ 44%]
test_price.py::test_price_with_tax[1000-8-1080] PASSED [ 55%]
test_price.py::test_price_with_tax[99-10-108] PASSED [ 66%]
test_price.py::test_price_with_tax[0-10-0] PASSED [ 77%]
1 組ごとに別のテストとして数えられ、値が名前に付きます。四捨五入版の price.py では test_price_with_tax[99-10-108] だけが失敗し、どの組が悪いかが一目で分かりました。
フィクスチャと tmp_path:準備を関数にまとめる
pytest では、unittest の setUp に当たる準備をフィクスチャという関数で書きます。テスト関数の引数に、フィクスチャの名前を書くと、pytest が準備した値を渡してくれます。
tmp_path は pytest に最初からあるフィクスチャで、テストごとに別の一時フォルダーを pathlib の Path で渡してくれます。後片付けも要りません。
import pytest
from price import total_from_file
@pytest.fixture
def price_file(tmp_path):
path = tmp_path / "prices.txt"
path.write_text("100\n200\n300\n", encoding="utf-8")
return path
def test_total(price_file):
assert total_from_file(price_file) == 660
price_file は自分で作ったフィクスチャで、その中で tmp_path を使っています。一時フォルダーはユーザーの Temp フォルダーの中の pytest-of-ユーザー名\pytest-番号\テスト名0\ に作られました。pytest の公式ドキュメントによると、初期設定では直近 3 回分の実行のフォルダーが残るので、失敗したときに中身を確かめられます。
浮動小数点数は pytest.approx で比べる
小数の計算結果を == で比べると、誤差で失敗することがあります。
def test_float():
total = 0.1 + 0.2
assert total == 0.3
def test_float_approx():
total = 0.1 + 0.2
assert total == pytest.approx(0.3)
test_misc.py::test_float FAILED [ 50%]
test_misc.py::test_float_approx PASSED [100%]
...
def test_float():
total = 0.1 + 0.2
> assert total == 0.3
E assert 0.30000000000000004 == 0.3
pytest.approx(0.3) は「0.3 に十分近ければ等しい」とみなします。初期設定では相対誤差 1e-6(100 万分の 1)まで、0 に近い値では絶対誤差 1e-12 までを許します。unittest では assertAlmostEqual を使います。0.1 + 0.2 が 0.3 にならない理由は「浮動小数点数の誤差とは?」で解説しています。
-k・-x・–lf:実行するテストを選ぶ
| オプション | 意味 | unittest で近いもの |
|---|---|---|
| -v | テストごとに結果を表示 | -v |
| -q | 表示を短くする | -q |
| -k 式 | 名前が式に合うテストだけ実行(大文字・小文字を区別しない。and・or・not が使える) | -k(大文字・小文字を区別する) |
| -x | 最初の失敗で止める | -f |
| –lf | 前回失敗したテストだけ実行 | なし |
| -s | print の出力をそのまま表示 | (初めから表示される) |
parametrize を追加した test_price.py(8 個のテスト)と、四捨五入版の price.py(失敗が 3 つ出る状態)で試しました。
python -m pytest test_price.py -k "round or format" -q
名前に round か format を含むテストだけが動き、2 failed, 6 deselected(2 つ失敗、6 つは選ばれなかった)になりました。-k "not format" のように除外もできます。PowerShell では、式を " で囲みます。
python -m pytest test_price.py -x では、最初の失敗のあと stopping after 1 failures と表示して止まり、結果は 1 failed, 1 passed でした。直したあとは python -m pytest --lf で、前回失敗したテストだけを実行し直せます。この例では run-last-failure: rerun previous 3 failures と表示され、3 つだけが実行されました。
unittest と pytest の比較
| 項目 | unittest | pytest |
|---|---|---|
| インストール | 不要(標準ライブラリ) | pip install pytest |
| テストの書き方 | TestCase を継承したクラスのメソッド | test_ で始まる関数(クラスも可) |
| 等しいかの確認 | self.assertEqual(a, b) | assert a == b |
| 例外の確認 | with self.assertRaises(例外): | with pytest.raises(例外, match=…): |
| 準備・後片付け | setUp / tearDown | フィクスチャ(tmp_path など) |
| 値を変えて同じテスト | subTest | @pytest.mark.parametrize |
| 相手側のテストの実行 | pytest 形式の関数は実行しない | unittest のテストも実行できる |
ライブラリを追加できない環境や、ちょっとしたスクリプトなら unittest、これから本格的にテストを書くなら pytest が書きやすいでしょう。
テストの置き場所と名前の付け方
pytest の公式ドキュメントによると、pytest は test_*.py または *_test.py という名前のファイルを探し、その中の test で始まる関数と、Test で始まるクラス(__init__ を持たないもの)の test で始まるメソッドを実行します。
unittest の初期設定は test*.py なので、両方で動かすなら test_price.py のように「test_ + テストしたいファイル名」にしておくのが無難です。小さなうちは同じフォルダーに置いてかまいません。ファイルが増えたら、次のように tests フォルダーに分けます。
myproject/
├── price.py
└── tests/
├── __init__.py (unittest で探させるなら必要。中身は空でよい)
└── test_price.py
- __init__.py がないと、unittest が tests の中を探さない。
py -m unittestがRan 0 testsとNO TESTS RANを表示して終わる。Python の公式ドキュメントでも、テストを探すフォルダーには __init__.py が必要だと説明されています - pytest コマンドで実行すると、
ModuleNotFoundError: No module named 'price'になる。python -m pytestなら動く。公式ドキュメントによると、python -m pytest は今いるフォルダーを sys.path(import するときに探す場所)に加えるという違いがあるため
pytest コマンドでも動かしたいときは、プロジェクトのフォルダーに pyproject.toml を作り、次のように書きます(書いたあと pytest コマンドでも成功しました)。
[tool.pytest.ini_options]
pythonpath = ["."]
よくある間違い
関数名が test で始まっていない
def check_upper(): のような名前は、テストとして集められません。失敗する assert を書いても、実行されないので何も表示されません。テストの数が少ないときは -v で名前を確かめます。
assert を書き忘れる
def test_no_assert():
"abc".upper() == "ABD"
比べた結果(False)を捨てているだけなので、このテストは PASSED になります。新しいテストを書いたら、一度わざと期待値を変えて、失敗することを確かめると安心です。
自分のファイルに pytest.py という名前を付ける
練習用のファイルを pytest.py という名前で保存し、同じフォルダーで python -m pytest を実行すると、テストは 1 つも動かず、自分の pytest.py が実行されるだけでした。今いるフォルダーのファイルが、インストールしたライブラリより先に見つかるためです。ライブラリと同じ名前は避けましょう。
まとめ
標準だけで済ませたいなら unittest(py -m unittest)、書きやすさと失敗時の分かりやすさなら pytest(venv に入れて python -m pytest)です。ファイルは test_*.py、関数は test_ で始め、小数は pytest.approx で比べましょう。
関連する記事・ツール
- Pythonの例外処理入門|try・except・finally・raiseの使い方
- Pythonの仮想環境venvの使い方|Windows・Linuxでの作成と有効化を解説
- pipの使い方|インストール・アップグレード・requirements.txtを実例で解説
- 浮動小数点数の誤差とは?0.1+0.2が0.3にならない理由と対処法
- Pythonのloggingの使い方|printから卒業するログ出力の基本と設定例
- テキスト差分比較ツール
- Pythonの型ヒント入門|typingの書き方とmypyで型の間違いを見つける方法