テストのパラメータ化¶
pytest を使用すると、テスト関数を簡単にパラメータ化できます。 基本的なドキュメントについては、フィクスチャとテスト関数をパラメータ化する方法 を参照してください。
以下では、組み込みのメカニズムを使用したいくつかの例を示します。
コマンドラインに応じたパラメータの組み合わせの生成¶
異なる計算パラメータでテストを実行し、パラメータ範囲をコマンドライン引数で決定したいとします。 まず、簡単な (何もしない) 計算テストを書いてみましょう：
# content of test_compute.py
def test_compute(param1):
assert param1 < 4
次に、このようなテスト構成を追加します：
# content of conftest.py
def pytest_addoption(parser):
parser.addoption("--all", action="store_true", help="run all combinations")
def pytest_generate_tests(metafunc):
if "param1" in metafunc.fixturenames:
if metafunc.config.getoption("all"):
end = 5
else:
end = 2
metafunc.parametrize("param1", range(end))
これは、--all を渡さない場合、2つのテストのみを実行することを意味します：
$ pytest -q test_compute.py
.. [100%]
2 passed in 0.12s
計算を2回だけ実行するので、2つのドットが表示されます。 完全な範囲を実行してみましょう：
$ pytest -q --all
....F [100%]
================================= FAILURES =================================
_____________________________ test_compute[4] ______________________________
param1 = 4
def test_compute(param1):
> assert param1 < 4
E assert 4 < 4
test_compute.py:4: AssertionError
========================= short test summary info ==========================
FAILED test_compute.py::test_compute[4] - assert 4 < 4
1 failed, 4 passed in 0.12s
予想通り、param1 の全範囲を実行すると、最後の値でエラーが発生します。
テストIDの異なるオプション¶
pytestは、パラメータ化されたテストの各値セットに対してテストIDとなる文字列を構築します。 これらのIDは、-k を使用して特定のケースを選択して実行するために使用でき、失敗した場合には特定のケースを識別します。 --collect-only オプションでpytestを実行すると、生成されたIDが表示されます。
数値、文字列、ブール値、およびNoneは、通常の文字列表現がテストIDに使用されます。 他のオブジェクトの場合、pytestは引数名に基づいて文字列を作成します：
# content of test_time.py
from datetime import datetime, timedelta
import pytest
testdata = [
(datetime(2001, 12, 12), datetime(2001, 12, 11), timedelta(1)),
(datetime(2001, 12, 11), datetime(2001, 12, 12), timedelta(-1)),
]
@pytest.mark.parametrize("a,b,expected", testdata)
def test_timedistance_v0(a, b, expected):
diff = a - b
assert diff == expected
@pytest.mark.parametrize("a,b,expected", testdata, ids=["forward", "backward"])
def test_timedistance_v1(a, b, expected):
diff = a - b
assert diff == expected
def idfn(val):
if isinstance(val, (datetime,)):
# note this wouldn't show any hours/minutes/seconds
return val.strftime("%Y%m%d")
@pytest.mark.parametrize("a,b,expected", testdata, ids=idfn)
def test_timedistance_v2(a, b, expected):
diff = a - b
assert diff == expected
@pytest.mark.parametrize(
"a,b,expected",
[
pytest.param(
datetime(2001, 12, 12), datetime(2001, 12, 11), timedelta(1), id="forward"
),
pytest.param(
datetime(2001, 12, 11), datetime(2001, 12, 12), timedelta(-1), id="backward"
),
],
)
def test_timedistance_v3(a, b, expected):
diff = a - b
assert diff == expected
test_timedistance_v0 では、pytestにテストIDを生成させます。
test_timedistance_v1 では、テストIDとして使用される文字列のリストとして ids を指定しました。 これらは簡潔ですが、維持するのが大変です。
test_timedistance_v2 では、テストIDの一部を生成する文字列表現を生成できる関数として ids を指定しました。 したがって、datetime 値は idfn によって生成されたラベルを使用しますが、timedelta オブジェクトのラベルを生成しなかったため、デフォルトのpytest表現を使用しています：
$ pytest test_time.py --collect-only
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y
rootdir: /home/sweet/project
collected 8 items
<Dir parametrize.rst-205>
<Module test_time.py>
<Function test_timedistance_v0[a0-b0-expected0]>
<Function test_timedistance_v0[a1-b1-expected1]>
<Function test_timedistance_v1[forward]>
<Function test_timedistance_v1[backward]>
<Function test_timedistance_v2[20011212-20011211-expected0]>
<Function test_timedistance_v2[20011211-20011212-expected1]>
<Function test_timedistance_v3[forward]>
<Function test_timedistance_v3[backward]>
======================== 8 tests collected in 0.12s ========================
test_timedistance_v3 では、テストIDを実際のデータと一緒に指定するために pytest.param を使用し、別々にリストするのではなく一緒に指定しました。
"testscenarios" の簡単な移植¶
ここでは、標準のunittestフレームワーク用のRobert Collinsのアドオンである testscenarios で構成されたテストを実行するための簡単な移植を示します。 pytestの Metafunc.parametrize の正しい引数を構築するために少し作業するだけです：
# content of test_scenarios.py
def pytest_generate_tests(metafunc):
idlist = []
argvalues = []
for scenario in metafunc.cls.scenarios:
idlist.append(scenario[0])
items = scenario[1].items()
argnames = [x[0] for x in items]
argvalues.append([x[1] for x in items])
metafunc.parametrize(argnames, argvalues, ids=idlist, scope="class")
scenario1 = ("basic", {"attribute": "value"})
scenario2 = ("advanced", {"attribute": "value2"})
class TestSampleWithScenarios:
scenarios = [scenario1, scenario2]
def test_demo1(self, attribute):
assert isinstance(attribute, str)
def test_demo2(self, attribute):
assert isinstance(attribute, str)
これは、次のコマンドで実行できる完全に自己完結型の例です：
$ pytest test_scenarios.py
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y
rootdir: /home/sweet/project
collected 4 items
test_scenarios.py .... [100%]
============================ 4 passed in 0.12s =============================
テストを収集するだけでも、テスト関数のバリエーションとして 'advanced' と 'basic' がきれいに表示されます：
$ pytest --collect-only test_scenarios.py
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y
rootdir: /home/sweet/project
collected 4 items
<Dir parametrize.rst-205>
<Module test_scenarios.py>
<Class TestSampleWithScenarios>
<Function test_demo1[basic]>
<Function test_demo2[basic]>
<Function test_demo1[advanced]>
<Function test_demo2[advanced]>
======================== 4 tests collected in 0.12s ========================
metafunc.parametrize() に対して、シナリオ値はクラススコープとして考慮すべきであると伝えました。 pytest-2.3では、これによりリソースベースの順序付けが行われます。
パラメータ化されたリソースのセットアップの延期¶
テスト関数のパラメータ化は収集時に行われます。 実際のテストが実行されるときにのみ、DB接続やサブプロセスなどの高価なリソースをセットアップするのが良い考えです。 これを達成する方法の簡単な例を示します。 このテストには db オブジェクトフィクスチャが必要です：
# content of test_backends.py
import pytest
def test_db_initialized(db):
# a dummy test
if db.__class__.__name__ == "DB2":
pytest.fail("deliberately failing for demo purposes")
これで、test_db_initialized 関数の2つの呼び出しを生成するテスト構成を追加し、実際のテスト呼び出しのためにデータベースオブジェクトを作成するファクトリを実装できます：
# content of conftest.py
import pytest
def pytest_generate_tests(metafunc):
if "db" in metafunc.fixturenames:
metafunc.parametrize("db", ["d1", "d2"], indirect=True)
class DB1:
"one database object"
class DB2:
"alternative database object"
@pytest.fixture
def db(request):
if request.param == "d1":
return DB1()
elif request.param == "d2":
return DB2()
else:
raise ValueError("invalid internal test config")
まず、収集時にどのように見えるかを見てみましょう：
$ pytest test_backends.py --collect-only
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y
rootdir: /home/sweet/project
collected 2 items
<Dir parametrize.rst-205>
<Module test_backends.py>
<Function test_db_initialized[d1]>
<Function test_db_initialized[d2]>
======================== 2 tests collected in 0.12s ========================
次に、テストを実行すると：
$ pytest -q test_backends.py
.F [100%]
================================= FAILURES =================================
_________________________ test_db_initialized[d2] __________________________
db = <conftest.DB2 object at 0xdeadbeef0001>
def test_db_initialized(db):
# a dummy test
if db.__class__.__name__ == "DB2":
> pytest.fail("deliberately failing for demo purposes")
E Failed: deliberately failing for demo purposes
test_backends.py:8: Failed
========================= short test summary info ==========================
FAILED test_backends.py::test_db_initialized[d2] - Failed: deliberately f...
1 failed, 1 passed in 0.12s
db == "DB1" の最初の呼び出しは成功し、db == "DB2" の2回目の呼び出しは失敗しました。 私たちの db フィクスチャ関数は、セットアップフェーズ中に各DB値をインスタンス化し、pytest_generate_tests は収集フェーズ中に test_db_initialized への2つの呼び出しを生成しました。
間接パラメータ化¶
テストをパラメータ化する際に indirect=True パラメータを使用すると、値を受け取るフィクスチャを使用してテストをパラメータ化し、それをテストに渡す前に行うことができます：
import pytest
@pytest.fixture
def fixt(request):
return request.param * 3
@pytest.mark.parametrize("fixt", ["a", "b"], indirect=True)
def test_indirect(fixt):
assert len(fixt) == 3
これは、たとえば、収集時にセットアップ手順を実行するのではなく、フィクスチャ内でテスト実行時により高価なセットアップを行うために使用できます。
特定の引数に間接を適用する¶
多くの場合、パラメータ化には複数の引数名が使用されます。 特定の引数に indirect パラメータを適用する機会があります。 これは、引数名のリストまたはタプルを indirect に渡すことで行うことができます。 以下の例では、x と y の2つのフィクスチャを使用する test_indirect 関数があります。 ここでは、フィクスチャ x の名前を含むリストを間接的に渡します。 間接パラメータはこの引数にのみ適用され、値 a がそれぞれのフィクスチャ関数に渡されます：
# content of test_indirect_list.py
import pytest
@pytest.fixture(scope="function")
def x(request):
return request.param * 3
@pytest.fixture(scope="function")
def y(request):
return request.param * 2
@pytest.mark.parametrize("x, y", [("a", "b")], indirect=["x"])
def test_indirect(x, y):
assert x == "aaa"
assert y == "b"
このテストの結果は成功します：
$ pytest -v test_indirect_list.py
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
cachedir: .pytest_cache
rootdir: /home/sweet/project
collecting ... collected 1 item
test_indirect_list.py::test_indirect[a-b] PASSED [100%]
============================ 1 passed in 0.12s =============================
クラスごとの構成を通じてテストメソッドをパラメータ化する¶
ここに、Michael Foordの unittest parametrizer に似たパラメータ化スキームを実装する pytest_generate_tests 関数の例がありますが、コードははるかに少なくなっています：
# content of ./test_parametrize.py
import pytest
def pytest_generate_tests(metafunc):
# called once per each test function
funcarglist = metafunc.cls.params[metafunc.function.__name__]
argnames = sorted(funcarglist[0])
metafunc.parametrize(
argnames, [[funcargs[name] for name in argnames] for funcargs in funcarglist]
)
class TestClass:
# a map specifying multiple argument sets for a test method
params = {
"test_equals": [dict(a=1, b=2), dict(a=3, b=3)],
"test_zerodivision": [dict(a=1, b=0)],
}
def test_equals(self, a, b):
assert a == b
def test_zerodivision(self, a, b):
with pytest.raises(ZeroDivisionError):
a / b
私たちのテストジェネレータは、各テスト関数に使用する引数セットを指定するクラスレベルの定義を検索します。 実行してみましょう：
$ pytest -q
F.. [100%]
================================= FAILURES =================================
________________________ TestClass.test_equals[1-2] ________________________
self = <test_parametrize.TestClass object at 0xdeadbeef0002>, a = 1, b = 2
def test_equals(self, a, b):
> assert a == b
E assert 1 == 2
test_parametrize.py:21: AssertionError
========================= short test summary info ==========================
FAILED test_parametrize.py::TestClass::test_equals[1-2] - assert 1 == 2
1 failed, 2 passed in 0.12s
複数のフィクスチャを使用したパラメータ化¶
ここに、異なるPythonインタープリタ間でオブジェクトのシリアル化をテストするためにパラメータ化されたテストを使用する実際の例があります。 3つの引数に対して異なる引数セットで実行される test_basic_objects 関数を定義します：
python1: 最初のPythonインタープリタ、オブジェクトをファイルにピクルダンプするために実行python2: 2番目のインタープリタ、オブジェクトをファイルからピクルロードするために実行obj: ダンプ/ロードされるオブジェクト
"""Module containing a parametrized tests testing cross-python serialization
via the pickle module."""
from __future__ import annotations
import shutil
import subprocess
import textwrap
import pytest
pythonlist = ["python3.9", "python3.10", "python3.11"]
@pytest.fixture(params=pythonlist)
def python1(request, tmp_path):
picklefile = tmp_path / "data.pickle"
return Python(request.param, picklefile)
@pytest.fixture(params=pythonlist)
def python2(request, python1):
return Python(request.param, python1.picklefile)
class Python:
def __init__(self, version, picklefile):
self.pythonpath = shutil.which(version)
if not self.pythonpath:
pytest.skip(f"{version!r} not found")
self.picklefile = picklefile
def dumps(self, obj):
dumpfile = self.picklefile.with_name("dump.py")
dumpfile.write_text(
textwrap.dedent(
rf"""
import pickle
f = open({str(self.picklefile)!r}, 'wb')
s = pickle.dump({obj!r}, f, protocol=2)
f.close()
"""
)
)
subprocess.run((self.pythonpath, str(dumpfile)), check=True)
def load_and_is_true(self, expression):
loadfile = self.picklefile.with_name("load.py")
loadfile.write_text(
textwrap.dedent(
rf"""
import pickle
f = open({str(self.picklefile)!r}, 'rb')
obj = pickle.load(f)
f.close()
res = eval({expression!r})
if not res:
raise SystemExit(1)
"""
)
)
print(loadfile)
subprocess.run((self.pythonpath, str(loadfile)), check=True)
@pytest.mark.parametrize("obj", [42, {}, {1: 3}])
def test_basic_objects(python1, python2, obj):
python1.dumps(obj)
python2.load_and_is_true(f"obj == {obj}")
すべてのPythonインタープリタがインストールされていない場合、実行するといくつかのスキップが発生し、それ以外の場合はすべての組み合わせ (3つのインタープリタ×3つのインタープリタ×3つのシリアル化/デシリアル化するオブジェクト) が実行されます：
. $ pytest -rs -q multipython.py
ssssssssssss...ssssssssssss [100%]
========================= short test summary info ==========================
SKIPPED [12] multipython.py:67: 'python3.9' not found
SKIPPED [12] multipython.py:67: 'python3.11' not found
3 passed, 24 skipped in 0.12s
オプションの実装/インポートのパラメータ化¶
特定のAPIの複数の実装の結果を比較したい場合、すでにインポートされた実装を受け取り、実装がインポートできない/利用できない場合にスキップされるテスト関数を書くことができます。 たとえば、「ベース」実装があり、他の (おそらく最適化された) 実装が同様の結果を提供する必要があるとします：
# content of conftest.py
import pytest
@pytest.fixture(scope="session")
def basemod(request):
return pytest.importorskip("base")
@pytest.fixture(scope="session", params=["opt1", "opt2"])
def optmod(request):
return pytest.importorskip(request.param)
次に、単純な関数のベース実装：
# content of base.py
def func1():
return 1
そして最適化されたバージョン：
# content of opt1.py
def func1():
return 1.0001
最後に小さなテストモジュール：
# content of test_module.py
def test_func1(basemod, optmod):
assert round(basemod.func1(), 3) == round(optmod.func1(), 3)
スキップの報告を有効にしてこれを実行すると：
$ pytest -rs test_module.py
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y
rootdir: /home/sweet/project
collected 2 items
test_module.py .s [100%]
========================= short test summary info ==========================
SKIPPED [1] test_module.py:3: could not import 'opt2': No module named 'opt2'
======================= 1 passed, 1 skipped in 0.12s =======================
opt2 モジュールがないため、test_func1 の2回目のテスト実行がスキップされたことがわかります。 いくつかの注意点：
conftest.pyファイルのフィクスチャ関数は「セッションスコープ」です。 インポートは1回だけで済むためです複数のテスト関数があり、インポートがスキップされた場合、レポートで
[1]カウントが増加するのがわかりますテスト関数に @pytest.mark.parametrize スタイルのパラメータ化を適用して、入力/出力値もパラメータ化できます。
個々のパラメータ化されたテストにマークまたはテストIDを設定する¶
pytest.param を使用して、個々のパラメータ化されたテストにマークを適用したり、テストIDを設定したりします。 たとえば：
# content of test_pytest_param_example.py
import pytest
@pytest.mark.parametrize(
"test_input,expected",
[
("3+5", 8),
pytest.param("1+7", 8, marks=pytest.mark.basic),
pytest.param("2+4", 6, marks=pytest.mark.basic, id="basic_2+4"),
pytest.param(
"6*9", 42, marks=[pytest.mark.basic, pytest.mark.xfail], id="basic_6*9"
),
],
)
def test_eval(test_input, expected):
assert eval(test_input) == expected
この例では、4つのパラメータ化されたテストがあります。 最初のテストを除いて、残りの3つのパラメータ化されたテストにはカスタムマーカー basic を付け、4番目のテストには組み込みのマーク xfail を使用して、このテストが失敗することを示します。 明示的にするために、いくつかのテストにテストIDを設定します。
次に、詳細モードで pytest を実行し、basic マーカーのみを使用します：
$ pytest -v -m basic
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
cachedir: .pytest_cache
rootdir: /home/sweet/project
collecting ... collected 24 items / 21 deselected / 3 selected
test_pytest_param_example.py::test_eval[1+7-8] PASSED [ 33%]
test_pytest_param_example.py::test_eval[basic_2+4] PASSED [ 66%]
test_pytest_param_example.py::test_eval[basic_6*9] XFAIL [100%]
=============== 2 passed, 21 deselected, 1 xfailed in 0.12s ================
結果として：
4つのテストが収集されました
1つのテストは
basicマークがないため、選択解除されました。basicマークの付いた3つのテストが選択されました。テスト
test_eval[1+7-8]は合格しましたが、名前は自動生成されており、混乱を招きます。テスト
test_eval[basic_2+4]は合格しました。テスト
test_eval[basic_6*9]は失敗することが予想され、実際に失敗しました。
条件付きの例外発生をパラメータ化する¶
pytest.raises() を pytest.mark.parametrize デコレータと一緒に使用して、一部のテストが例外を発生させ、他のテストが発生させないパラメータ化されたテストを書きます。
contextlib.nullcontext を使用して、例外が発生しないが何らかの値を返すべきテストケースをテストできます。 値は enter_result パラメータとして指定され、with ステートメントのターゲット (以下の例では e) として使用できます。
たとえば：
from contextlib import nullcontext
import pytest
@pytest.mark.parametrize(
"example_input,expectation",
[
(3, nullcontext(2)),
(2, nullcontext(3)),
(1, nullcontext(6)),
(0, pytest.raises(ZeroDivisionError)),
],
)
def test_division(example_input, expectation):
"""Test how much I know division."""
with expectation as e:
assert (6 / example_input) == e
上記の例では、最初の3つのテストケースは例外なしで実行されるべきですが、4番目のテストケースは ZeroDivisionError 例外を発生させるべきであり、これはpytestによって期待されます。