API リファレンス¶

このページには pytest の API に関する完全なリファレンスが含まれています。

定数¶

pytest.version¶

現在の pytest のバージョンを文字列として:

>>> import pytest
>>> pytest.__version__
'7.0.0'

pytest.version_tuple¶

Added in version 7.0.

現在の pytest のバージョンをタプルとして:

>>> import pytest
>>> pytest.version_tuple
(7, 0, 0)

プレリリースの場合、最後の要素はプレリリースバージョンの文字列になります:

>>> import pytest
>>> pytest.version_tuple
(7, 0, '0rc1')

関数¶

pytest.approx¶

approx(expected, rel=None, abs=None, nan_ok=False)[ソース]¶

2 つの数値 (または順序付けられた数値のシーケンス) がある許容範囲内で互いに等しいことをアサートします。

Floating-Point Arithmetic: Issues and Limitations により、直感的に等しいと期待される数値が常にそうであるとは限りません:

>>> 0.1 + 0.2 == 0.3
False

この問題はテストを書くときによく遭遇します。例えば、浮動小数点値が期待通りであることを確認する場合です。この問題に対処する方法の一つは、2 つの浮動小数点数が適切な許容範囲内で等しいことをアサートすることです:

>>> abs((0.1 + 0.2) - 0.3) < 1e-6
True

しかし、このような比較は書くのが面倒で理解しにくいです。さらに、上記のような絶対比較は通常推奨されません。なぜなら、すべての状況にうまく適用できる許容範囲がないからです。 1e-6 は 1 の周りの数値には良いですが、非常に大きな数値には小さすぎ、非常に小さな数値には大きすぎます。許容範囲を期待値の分数として表現する方が良いですが、そのような相対比較は正確かつ簡潔に書くのがさらに難しいです。

approx クラスは、できるだけ直感的な構文を使用して浮動小数点の比較を行います:

>>> from pytest import approx
>>> 0.1 + 0.2 == approx(0.3)
True

同じ構文は、順序付けられた数値のシーケンスにも適用されます:

>>> (0.1 + 0.2, 0.2 + 0.4) == approx((0.3, 0.6))
True

numpy 配列:

>>> import numpy as np                                                          
>>> np.array([0.1, 0.2]) + np.array([0.2, 0.4]) == approx(np.array([0.3, 0.6])) 
True

そして、スカラーに対する numpy 配列:

>>> import numpy as np                                         
>>> np.array([0.1, 0.2]) + np.array([0.2, 0.1]) == approx(0.3) 
True

approx はシーケンスの相対位置を曖昧さなく推測する必要があるため、順序付けられたシーケンスのみがサポートされます。これは、sets や他の順序付けられていないシーケンスはサポートされないことを意味します。

最後に、辞書の値も比較できます:

>>> {'a': 0.1 + 0.2, 'b': 0.2 + 0.4} == approx({'a': 0.3, 'b': 0.6})
True

両方のマッピングが同じキーを持ち、それぞれの値が期待される許容範囲に一致する場合、比較は真となります。

許容範囲

デフォルトでは、approx は期待値の 1e-6 (すなわち百万分の一) の相対許容範囲内の数値を等しいと見なします。この処理は、期待値が 0.0 の場合に驚くべき結果をもたらします。なぜなら、0.0 自体以外は 0.0 に相対的に近いものはないからです。このケースを驚かせないように処理するために、approx は期待値の 1e-12 の絶対許容範囲内の数値も等しいと見なします。無限大と NaN は特別なケースです。無限大は相対許容範囲に関係なく、それ自体としか等しく見なされません。 NaN はデフォルトでは何とも等しく見なされませんが、nan_ok 引数を True に設定することでそれ自体と等しく見なすことができます。 (これは、NaN を「データなし」を意味するために使用する配列を比較するのを容易にすることを目的としています。)

相対許容範囲と絶対許容範囲の両方は、approx コンストラクタに引数を渡すことで変更できます:

>>> 1.0001 == approx(1)
False
>>> 1.0001 == approx(1, rel=1e-3)
True
>>> 1.0001 == approx(1, abs=1e-3)
True

abs を指定して rel を指定しない場合、比較は相対許容範囲を全く考慮しません。言い換えれば、デフォルトの相対許容範囲 1e-6 内にある 2 つの数値は、指定された絶対許容範囲を超える場合、依然として等しくないと見なされます。 abs と rel の両方を指定した場合、いずれかの許容範囲が満たされれば数値は等しいと見なされます:

>>> 1 + 1e-8 == approx(1)
True
>>> 1 + 1e-8 == approx(1, abs=1e-12)
False
>>> 1 + 1e-8 == approx(1, rel=1e-6, abs=1e-12)
True

approx を使用して非数値型、または非数値型を含む辞書やシーケンスを比較することもできます。その場合、厳密な等価性に戻ります。これは、オプションの値を含む可能性のある辞書やシーケンスを比較するのに役立ちます:

>>> {"required": 1.0000005, "optional": None} == approx({"required": 1, "optional": None})
True
>>> [None, 1.0000005] == approx([None,1])
True
>>> ["foo", 1.0000005] == approx([None,1])
False

approx を使用することを考えている場合、浮動小数点数を比較する他の良い方法とどのように比較されるかを知りたいかもしれません。これらのアルゴリズムはすべて相対許容範囲と絶対許容範囲に基づいており、ほとんどの場合一致するはずですが、意味のある違いがあります:

math.isclose(a, b, rel_tol=1e-9, abs_tol=0.0): 相対許容範囲が a または b のいずれかに対して満たされるか、絶対許容範囲が満たされる場合に True です。相対許容範囲は a と b の両方に対して計算されるため、このテストは対称的です (つまり、a も b も「基準値」ではありません)。 0.0 と比較する場合は、絶対許容範囲を指定する必要があります。デフォルトでは許容範囲がないためです。詳細情報: math.isclose().
numpy.isclose(a, b, rtol=1e-5, atol=1e-8): a と b の差が b に対する相対許容範囲と絶対許容範囲の合計より小さい場合に True です。相対許容範囲は b に対してのみ計算されるため、このテストは非対称であり、b を基準値と見なすことができます。シーケンスの比較のサポートは numpy.allclose() によって提供されます。詳細情報: numpy.isclose.
unittest.TestCase.assertAlmostEqual(a, b): a と b が絶対許容範囲 1e-7 内にある場合に True です。相対許容範囲は考慮されないため、この関数は非常に大きな数値や非常に小さな数値には適していません。また、unittest.TestCase のサブクラスでのみ利用可能であり、PEP8 に従っていないため見た目が悪いです。詳細情報: unittest.TestCase.assertAlmostEqual().
a == pytest.approx(b, rel=1e-6, abs=1e-12): 相対許容範囲が b に対して満たされるか、絶対許容範囲が満たされる場合に True です。相対許容範囲は b に対してのみ計算されるため、このテストは非対称であり、b を基準値と見なすことができます。絶対許容範囲を明示的に指定し、相対許容範囲を指定しない特別な場合には、絶対許容範囲のみが考慮されます。

注釈

approx は numpy 配列を処理できますが、比較、NaN、または ULP ベースの許容範囲のサポートが必要な場合は、Test support (numpy.testing) の専門のテストヘルパーをお勧めします。

正規表現を使用して文字列を一致させるには、re_assert パッケージの Matches を使用できます。

警告

バージョン 3.2 で変更.

一貫性のない動作を避けるために、>, >=, < および <= 比較では TypeError が発生します。以下の例は問題を示しています:

assert approx(0.1) > 0.1 + 1e-10  # calls approx(0.1).__gt__(0.1 + 1e-10)
assert 0.1 + 1e-10 > approx(0.1)  # calls approx(0.1).__lt__(0.1 + 1e-10)

2 番目の例では approx(0.1).__le__(0.1 + 1e-10) が呼び出されることを期待します。しかし、代わりに approx(0.1).__lt__(0.1 + 1e-10) が比較に使用されます。これは、リッチ比較の呼び出し階層が固定された動作に従うためです。詳細情報: object.__ge__()

バージョン 3.7.1 で変更: approx は、非数値型の辞書値またはシーケンス要素に遭遇した場合に TypeError を発生させます。

バージョン 6.1.0 で変更: approx は TypeError を発生させる代わりに、非数値型に対して厳密な等価性に戻ります。

pytest.fail¶

チュートリアル: 成功しないテストを処理するために skip と xfail を使用する方法

fail(reason[, pytrace=True])[ソース]¶

指定されたメッセージで実行中のテストを明示的に失敗させます。

パラメータ:

reason (str) -- 失敗の理由としてユーザーに表示するメッセージ。
pytrace (bool) -- False の場合、msg は完全な失敗情報を表し、Python のトレースバックは報告されません。

例外:

pytest.fail.Exception -- 発生する例外。

class pytest.fail.Exception¶: pytest.fail() によって発生する例外。

pytest.skip¶

skip(reason[, allow_module_level=False])[ソース]¶

指定されたメッセージで実行中のテストをスキップします。

この関数はテスト中 (セットアップ、コール、またはティアダウン) または allow_module_level フラグを使用してコレクション中にのみ呼び出す必要があります。この関数は doctests でも呼び出すことができます。

パラメータ:

reason (str) -- スキップの理由としてユーザーに表示するメッセージ。
allow_module_level (bool) -- この関数をモジュールレベルで呼び出すことを許可します。モジュールレベルでスキップ例外を発生させると、モジュールの実行が停止し、skip 呼び出しの前に定義されたテストも含めて、モジュール内のすべてのテストの収集が防止されます。デフォルトは False です。

例外:

pytest.skip.Exception -- 発生する例外。

注釈

プラットフォームや依存関係が一致しないなどの特定の条件下でテストをスキップすることを宣言するには、可能な限り pytest.mark.skipif マーカーを使用する方が良いです。同様に、doctest を静的にスキップするには # doctest: +SKIP ディレクティブを使用します (doctest.SKIP を参照)。

class pytest.skip.Exception¶: pytest.skip() によって発生する例外。

pytest.importorskip¶

importorskip(modname, minversion=None, reason=None, *, exc_type=None)[ソース]¶

要求されたモジュール modname をインポートして返すか、モジュールをインポートできない場合は現在のテストをスキップします。

パラメータ:

modname (str) -- インポートするモジュールの名前。
minversion (str | None) -- 指定された場合、インポートされたモジュールの __version__ 属性は少なくともこの最小バージョンでなければなりません。そうでない場合、テストはスキップされます。
reason (str | None) -- 指定された場合、モジュールをインポートできないときにこの理由がメッセージとして表示されます。
exc_type (type[ImportError] | None) -- モジュールをスキップするためにキャプチャする必要がある例外。 ImportError またはそのサブクラスでなければなりません。モジュールをインポートできても ImportError が発生した場合、pytest はユーザーに警告を発します。多くの場合、ユーザーはモジュールが見つからないことを期待しています (この場合は ModuleNotFoundError が発生します)。この警告は exc_type=ImportError を明示的に渡すことで抑制できます。詳細は pytest.importorskip default behavior regarding ImportError を参照してください。

戻り値:

インポートされたモジュール。これはその標準名に割り当てる必要があります。

例外:

pytest.skip.Exception -- モジュールをインポートできない場合。

戻り値の型:

Any

例:

docutils = pytest.importorskip("docutils")

Added in version 8.2: exc_type パラメータ。

pytest.xfail¶

xfail(reason='')[ソース]¶

指定された理由で実行中のテストまたはセットアップ関数を強制的に xfail します。

この関数はテスト中 (セットアップ、コール、またはティアダウン) にのみ呼び出す必要があります。

xfail() を使用した後、他のコードは実行されません (これは内部的に例外を発生させることで実装されています)。

パラメータ:: reason (str) -- xfail の理由としてユーザーに表示するメッセージ。

注釈

既知のバグや欠落している機能などの特定の条件下でテストを xfail することを宣言するには、可能な限り pytest.mark.xfail マーカーを使用する方が良いです。

例外:: pytest.xfail.Exception -- 発生する例外。

class pytest.xfail.Exception¶: pytest.xfail() によって発生する例外。

pytest.exit¶

exit(reason[, returncode=None])[ソース]¶

テストプロセスを終了します。

パラメータ:

reason (str) -- pytest を終了する理由として表示するメッセージ。 reason は msg が非推奨であるためにのみデフォルト値を持ちます。
returncode (int | None) -- pytest を終了するときに使用されるリターンコード。 None は 0 (エラーなし) と同じ意味です。 sys.exit() と同じです。

例外:

pytest.exit.Exception -- 発生する例外。

class pytest.exit.Exception¶: pytest.exit() によって発生する例外。

pytest.main¶

チュートリアル: Python コードから pytest を呼び出す

main(args=None, plugins=None)[ソース]¶

インプロセステストを実行します。

パラメータ:

args (list[str] | PathLike[str] | None) -- コマンドライン引数のリスト。 None または指定されていない場合、プロセスのコマンドライン (sys.argv) から直接引数を読み取るのがデフォルトです。
plugins (Sequence[str | object] | None) -- 初期化中に自動登録されるプラグインオブジェクトのリスト。

戻り値:

終了コード。

戻り値の型:

int | ExitCode

pytest.param¶

param(*values[, id][, marks])[ソース]¶

pytest.mark.parametrize 呼び出しや parametrized fixtures でパラメータを指定します。

@pytest.mark.parametrize(
    "test_input,expected",
    [
        ("3+5", 8),
        pytest.param("6*9", 42, marks=pytest.mark.xfail),
    ],
)
def test_eval(test_input, expected):
    assert eval(test_input) == expected

パラメータ:

values (object) -- パラメータセットの値の可変引数を順番に。
marks (MarkDecorator | Collection[MarkDecorator | Mark]) -- このパラメータセットに適用される単一のマークまたはマークのリスト。
id (str | None) -- このパラメータセットに付与する ID。

pytest.raises¶

チュートリアル: 予期される例外に関するアサーション

with raises(expected_exception: type[E] | tuple[type[E], ...], *, match: str | Pattern[str] | None = ...) → RaisesContext[E] as excinfo[ソース]¶

with raises(expected_exception: type[E] | tuple[type[E], ...], func: Callable[[...], Any], *args: Any, **kwargs: Any) → ExceptionInfo[E] as excinfo

コードブロック/関数呼び出しが例外タイプまたはそのサブクラスのいずれかを発生させることをアサートします。

パラメータ:

expected_exception -- 期待される例外タイプ、または複数の可能な例外タイプのいずれかが期待される場合はタプル。渡された例外のサブクラスも一致することに注意してください。
match (str | re.Pattern[str] | None) -- 指定された場合、正規表現を含む文字列、または正規表現オブジェクトが例外の文字列表現およびその PEP 678 __notes__ に対して re.search() を使用してテストされます。 special characters を含む可能性のあるリテラル文字列に一致させるには、最初にパターンを re.escape() でエスケープできます。 (これは pytest.raises がコンテキストマネージャとして使用される場合にのみ使用され、そうでない場合は関数に渡されます。関数として pytest.raises を使用する場合は、pytest.raises(Exc, func, match="passed on").match("my pattern") を使用できます。)

コンテキストマネージャとして pytest.raises を使用すると、指定されたタイプの例外またはそのサブクラスのいずれかをキャプチャします:

>>> import pytest
>>> with pytest.raises(ZeroDivisionError):
...    1/0

コードブロックが期待される例外 (ZeroDivisionError 上記の例) を発生させない場合、またはまったく例外を発生させない場合、チェックは失敗します。

キーワード引数 match を使用して、例外がテキストまたは正規表現に一致することをアサートすることもできます:

>>> with pytest.raises(ValueError, match='must be 0 or None'):
...     raise ValueError("value must be 0 or None")

>>> with pytest.raises(ValueError, match=r'must be \d+$'):
...     raise ValueError("value must be 42")

match 引数は、フォーマットされた例外文字列を検索します。これには、PEP-678 __notes__ が含まれます。

>>> with pytest.raises(ValueError, match=r"had a note added"):  
...     e = ValueError("value must be 42")
...     e.add_note("had a note added")
...     raise e

コンテキストマネージャは ExceptionInfo オブジェクトを生成し、キャプチャされた例外の詳細を調査するために使用できます。

>>> with pytest.raises(ValueError) as exc_info:
...     raise ValueError("value must be 42")
>>> assert exc_info.type is ValueError
>>> assert exc_info.value.args[0] == "value must be 42"

警告

pytest.raises はサブクラスに一致するため、次のように Exception に一致させる場合は注意してください。

with pytest.raises(Exception):  # Careful, this will catch ANY exception raised.
    some_function()

Exception はほとんどすべての例外の基底クラスであるため、特定の例外を期待してこれを書いたユーザーが、リファクタリング中に導入されたバグにより他の例外が発生している場合に、これが実際のバグを隠すことが容易です。

任意の 例外をキャッチしたいと確信している場合を除き、Exception をキャッチするために pytest.raises を使用することは避けてください。

注釈

pytest.raises をコンテキストマネージャとして使用する場合、通常のコンテキストマネージャのルールが適用され、発生した例外はコンテキストマネージャのスコープ内の最後の行でなければならないことに注意する価値があります。その後のコード行はコンテキストマネージャのスコープ内では実行されません。例えば:

>>> value = 15
>>> with pytest.raises(ValueError) as exc_info:
...     if value > 10:
...         raise ValueError("value must be <= 10")
...     assert exc_info.type is ValueError  # This will not execute.

代わりに、次のアプローチを取る必要があります (スコープの違いに注意):

>>> with pytest.raises(ValueError) as exc_info:
...     if value > 10:
...         raise ValueError("value must be <= 10")
...
>>> assert exc_info.type is ValueError

pytest.mark.parametrize を使用する

pytest.mark.parametrize を使用する場合、いくつかの実行で例外を発生させ、他の実行では発生させないようにテストをパラメータ化することが可能です。

例については条件付きの例外発生をパラメータ化するを参照してください。

参考

詳細な議論と他の例については予期される例外に関するアサーションを参照してください。

レガシーフォーム

呼び出されるラムダを渡すことで、呼び出し可能なものを指定することができます:

>>> raises(ZeroDivisionError, lambda: 1/0)
<ExceptionInfo ...>

または、引数付きの任意の呼び出し可能なものを指定することもできます:

>>> def f(x): return 1/x
...
>>> raises(ZeroDivisionError, f, 0)
<ExceptionInfo ...>
>>> raises(ZeroDivisionError, f, x=0)
<ExceptionInfo ...>

上記の形式は完全にサポートされていますが、新しいコードには推奨されません。コンテキストマネージャ形式の方が読みやすく、エラーが発生しにくいと考えられているためです。

注釈

Python でキャッチされた例外オブジェクトと同様に、返された ExceptionInfo オブジェクトへのローカル参照を明示的にクリアすることで、Python インタープリタがガベージコレクションを高速化するのに役立ちます。

これらの参照をクリアすることで、参照サイクル (ExceptionInfo --> キャッチされた例外 --> 例外を発生させるフレームスタック --> 現在のフレームスタック --> ローカル変数 --> ExceptionInfo) が破壊され、Python がそのサイクルから参照されるすべてのオブジェクト (現在のフレームのすべてのローカル変数を含む) を次の循環ガベージコレクション実行まで生きている状態に保ちます。詳細な情報は、公式の Python ドキュメントの the try statement にあります。

pytest.deprecated_call¶

チュートリアル: コードが非推奨警告をトリガーすることを確認する

with deprecated_call(*, match: str | Pattern[str] | None = ...) → WarningsRecorder[ソース]¶

with deprecated_call(func: Callable[[...], T], *args: Any, **kwargs: Any) → T

コードが DeprecationWarning または PendingDeprecationWarning または FutureWarning を生成することをアサートします。

この関数はコンテキストマネージャとして使用できます:

>>> import warnings
>>> def api_call_v2():
...     warnings.warn('use v3 of this api', DeprecationWarning)
...     return 200

>>> import pytest
>>> with pytest.deprecated_call():
...    assert api_call_v2() == 200

関数と *args および **kwargs を渡すことで使用することもできます。この場合、func(*args, **kwargs) を呼び出すと、上記のいずれかの警告タイプが生成されることを保証します。戻り値は関数の戻り値です。

コンテキストマネージャ形式では、キーワード引数 match を使用して、警告がテキストまたは正規表現に一致することをアサートできます。

コンテキストマネージャは、発生した警告ごとに 1 つの warnings.WarningMessage オブジェクトのリストを生成します。

pytest.register_assert_rewrite¶

チュートリアル: アサーションの書き換え

register_assert_rewrite(*names)[ソース]¶

インポート時に書き換えられる 1 つ以上のモジュール名を登録します。

この関数は、このモジュールまたはパッケージ内のすべてのモジュールがアサートステートメントが書き換えられるようにします。したがって、通常はパッケージを使用するプラグインの __init__.py で実際にモジュールがインポートされる前にこれを呼び出すようにしてください。

パラメータ:: names (str) -- 登録するモジュール名。

pytest.warns¶

チュートリアル: warns 関数を使用して警告をアサートする

with warns(expected_warning: type[Warning] | tuple[type[Warning], ...] = <class 'Warning'>, *, match: str | ~typing.Pattern[str] | None = None) → WarningsChecker[ソース]¶

with warns(expected_warning: type[Warning] | tuple[type[Warning], ...], func: Callable[[...], T], *args: Any, **kwargs: Any) → T

コードが特定のクラスの警告を発生させることをアサートします。

具体的には、パラメータ expected_warning は警告クラスまたは警告クラスのタプルであり、with ブロック内のコードは、そのクラスまたはクラスの少なくとも 1 つの警告を発行する必要があります。

このヘルパーは、発行された警告ごとに 1 つの warnings.WarningMessage オブジェクトのリストを生成します (expected_warning であるかどうかに関係なく)。 pytest 8.0 以降、一致しない警告もコンテキストが閉じると再発行されます。

この関数はコンテキストマネージャとして使用できます:

>>> import pytest
>>> with pytest.warns(RuntimeWarning):
...    warnings.warn("my warning", RuntimeWarning)

コンテキストマネージャ形式では、キーワード引数 match を使用して、警告がテキストまたは正規表現に一致することをアサートできます:

>>> with pytest.warns(UserWarning, match='must be 0 or None'):
...     warnings.warn("value must be 0 or None", UserWarning)

>>> with pytest.warns(UserWarning, match=r'must be \d+$'):
...     warnings.warn("value must be 42", UserWarning)

>>> with pytest.warns(UserWarning):  # catch re-emitted warning
...     with pytest.warns(UserWarning, match=r'must be \d+$'):
...         warnings.warn("this is not here", UserWarning)
Traceback (most recent call last):
  ...
Failed: DID NOT WARN. No warnings of type ...UserWarning... were emitted...

pytest.mark.parametrize を使用する

pytest.mark.parametrize を使用すると、いくつかの実行で警告を発生させ、他の実行では発生させないようにテストをパラメータ化することが可能です。

これは例外と同じ方法で達成できます。例については条件付きの例外発生をパラメータ化するを参照してください。

pytest.freeze_includes¶

チュートリアル: pytestのフリーズ

freeze_includes()[ソース]¶

cx_freeze によって含まれるべき pytest で使用されるモジュール名のリストを返します。

マーク¶

マークは、テスト関数 (ただしフィクスチャではない) にメタデータを適用するために使用でき、その後フィクスチャやプラグインからアクセスできます。

pytest.mark.filterwarnings¶

チュートリアル: @pytest.mark.filterwarnings

マークされたテスト項目に警告フィルタを追加します。

pytest.mark.filterwarnings(filter)¶

パラメータ:: filter (str) -- 警告仕様文字列 は、Python ドキュメントの The Warnings Filter セクションで指定されている (action, message, category, module, lineno) のタプルの内容で構成され、":" で区切られます。オプションのフィールドは省略できます。フィルタリングに渡されるモジュール名は正規表現でエスケープされません。例: .. code-block:: python @pytest.mark.filterwarnings("ignore:.*usage will be deprecated.*:DeprecationWarning") def test_foo(): ...

pytest.mark.parametrize¶

チュートリアル: フィクスチャとテスト関数をパラメータ化する方法

このマークは pytest.Metafunc.parametrize() と同じシグネチャを持っています。そちらを参照してください。

pytest.mark.skip¶

チュートリアル: テスト関数のスキップ

テスト関数を無条件でスキップします。

pytest.mark.skip(reason=None)¶

パラメータ:: reason (str) -- テスト関数がスキップされる理由。

pytest.mark.skipif¶

チュートリアル: テスト関数のスキップ

条件が True の場合、テスト関数をスキップします。

pytest.mark.skipif(condition, *, reason=None)¶

パラメータ:

condition (bool or str) -- 条件がスキップされるべきかどうかの True/False または condition string。
reason (str) -- テスト関数がスキップされる理由。

pytest.mark.usefixtures¶

チュートリアル: クラスおよびモジュールで usefixtures を使用してフィクスチャを使用する

テスト関数を指定されたフィクスチャ名を使用するようにマークします。

pytest.mark.usefixtures(*names)¶

パラメータ:: args -- フィクスチャの名前。文字列として。

注釈

フックで usefixtures を使用する場合、テストセットアップ前のテスト関数に適用されるときのみフィクスチャをロードできます (たとえば pytest_collection_modifyitems フックで)。

また、このマークは フィクスチャ に適用された場合には効果がありません。

pytest.mark.xfail¶

チュートリアル: XFail: テスト関数が失敗すると予想されることをマークする

テスト関数を 失敗することが期待される としてマークします。

pytest.mark.xfail(condition=False, *, reason=None, raises=None, run=True, strict=xfail_strict)¶

パラメータ:

condition (Union[bool, str]) -- テスト関数を xfail としてマークする条件 (True/False または condition string)。 bool の場合は reason も指定する必要があります (condition string を参照)。
reason (str) -- テスト関数が xfail としてマークされる理由。
raises (Type[Exception]) -- テスト関数によって発生することが期待される例外クラス (またはクラスのタプル)。他の例外はテストに失敗します。渡されたクラスのサブクラスも一致する結果になることに注意してください (except ステートメントの動作と同様)。
run (bool) -- テスト関数が実際に実行されるべきかどうか。 False の場合、関数は常に xfail となり、実行されません (関数がセグフォルトしている場合に便利です)。
strict (bool) --
- False の場合、関数はターミナル出力に xfailed として表示され、失敗した場合は xpass として表示されます。どちらの場合も、これはテストスイート全体を失敗させることはありません。これは、後で対処するために flaky テスト (ランダムに失敗するテスト) をマークするのに特に便利です。
- True の場合、関数は失敗した場合に xfailed としてターミナル出力に表示されますが、予期せずにパスした場合はテストスイートを失敗させます。これは、常に失敗する関数をマークし、予期せずにパスし始めた場合には明確な指示があるべきである関数をマークするのに特に便利です (たとえば、新しいリリースで既知のバグが修正された場合)。
デフォルトは xfail_strict で、デフォルトは False です。

カスタムマーク¶

マークは、ファクトリオブジェクト pytest.mark を使用して動的に作成され、デコレータとして適用されます。

例:

@pytest.mark.timeout(10, "slow", method="thread")
def test_function(): ...

収集された Item に Mark オブジェクトを作成してアタッチし、その後、フィクスチャやフックで Node.iter_markers を使用してアクセスできます。 mark オブジェクトには以下の属性があります:

mark.args == (10, "slow")
mark.kwargs == {"method": "thread"}

複数のカスタムマーカーを使用する例:

@pytest.mark.timeout(10, "slow", method="thread")
@pytest.mark.slow
def test_function(): ...

Node.iter_markers または Node.iter_markers_with_node が複数のマーカーで使用されると、関数に最も近いマーカーが最初に反復されます。上記の例では、@pytest.mark.slow が最初に続いて @pytest.mark.timeout(...) になります。

フィクスチャ¶

チュートリアル: フィクスチャのリファレンス

フィクスチャは、テスト関数や他のフィクスチャによって、引数名として宣言することで要求されます。

フィクスチャを必要とするテストの例:

def test_output(capsys):
    print("hello")
    out, err = capsys.readouterr()
    assert out == "hello\n"

別のフィクスチャを必要とするフィクスチャの例:

@pytest.fixture
def db_session(tmp_path):
    fn = tmp_path / "db.file"
    return connect(fn)

詳細については、完全な fixtures docs を参照してください。

@pytest.fixture¶

@fixture(fixture_function: FixtureFunction, *, scope: Literal['session', 'package', 'module', 'class', 'function'] | Callable[[str, Config], Literal['session', 'package', 'module', 'class', 'function']] = 'function', params: Iterable[object] | None = None, autouse: bool = False, ids: Sequence[object | None] | Callable[[Any], object | None] | None = None, name: str | None = None) → FixtureFunction[ソース]¶

@fixture(fixture_function: None = None, *, scope: Literal['session', 'package', 'module', 'class', 'function'] | Callable[[str, Config], Literal['session', 'package', 'module', 'class', 'function']] = 'function', params: Iterable[object] | None = None, autouse: bool = False, ids: Sequence[object | None] | Callable[[Any], object | None] | None = None, name: str | None = None) → FixtureFunctionMarker

フィクスチャファクトリ関数をマークするためのデコレータ。

このデコレータは、パラメータの有無にかかわらず、フィクスチャ関数を定義するために使用できます。

フィクスチャ関数の名前は、テストの実行前にその呼び出しを引き起こすために参照されることがあります: テストモジュールやクラスは pytest.mark.usefixtures(fixturename) マーカーを使用できます。

テスト関数は、入力引数として直接フィクスチャ名を使用でき、その場合、フィクスチャ関数から返されるフィクスチャインスタンスが注入されます。

フィクスチャは return または yield ステートメントを使用してテスト関数に値を提供できます。 yield を使用する場合、yield ステートメントの後のコードブロックはテストの結果に関係なくティアダウンコードとして実行され、正確に一度だけ yield されなければなりません。

パラメータ:

scope -- このフィクスチャが共有されるスコープ; "function" (デフォルト)、"class"、"module"、"package"、または "session" のいずれか。このパラメータは (fixture_name, config) をパラメータとして受け取り、上記の値のいずれかを持つ str を返すコール可能なものでもかまいません。詳細については、ドキュメントの動的スコープを参照してください。
params -- フィクスチャ関数とそれを使用するすべてのテストの複数の呼び出しを引き起こすパラメータのオプションのリスト。現在のパラメータは request.param で利用できます。
autouse -- True の場合、フィクスチャ関数はそれを見ることができるすべてのテストに対してアクティブになります。 False (デフォルト) の場合、フィクスチャをアクティブにするには明示的な参照が必要です。
ids -- パラメータに対応する ID のシーケンス。これらはテスト ID の一部となります。 ID が提供されない場合、それらはパラメータから自動的に生成されます。
name -- フィクスチャの名前。これはデコレートされた関数の名前がデフォルトになります。フィクスチャが定義されているモジュール内で使用される場合、フィクスチャの関数名はフィクスチャを要求する関数引数によって隠されます。これを解決する方法の一つは、デコレートされた関数を fixture_<fixturename> と名付け、@pytest.fixture(name='<fixturename>') を使用することです。

capfd¶

チュートリアル: stdout/stderr 出力をキャプチャする方法

capfd()[ソース]¶

ファイルディスクリプタ 1 と 2 への書き込みのテキストキャプチャを有効にします。

キャプチャされた出力は capfd.readouterr() メソッド呼び出しを通じて利用可能で、(out, err) の名前付きタプルを返します。 out と err は text オブジェクトになります。

インスタンスを返します CaptureFixture[str]。

例:

def test_system_echo(capfd):
    os.system('echo "hello"')
    captured = capfd.readouterr()
    assert captured.out == "hello\n"

capfdbinary¶

チュートリアル: stdout/stderr 出力をキャプチャする方法

capfdbinary()[ソース]¶

ファイルディスクリプタ 1 と 2 への書き込みのバイトキャプチャを有効にします。

キャプチャされた出力は capfd.readouterr() メソッド呼び出しを通じて利用可能で、(out, err) の名前付きタプルを返します。 out と err は byte オブジェクトになります。

インスタンスを返します CaptureFixture[bytes]。

例:

def test_system_echo(capfdbinary):
    os.system('echo "hello"')
    captured = capfdbinary.readouterr()
    assert captured.out == b"hello\n"

caplog¶

チュートリアル: ロギングを管理する方法

caplog()[ソース]¶

ログキャプチャへのアクセスと制御。

キャプチャされたログは次のプロパティ/メソッドを通じて利用可能です:

* caplog.messages        -> list of format-interpolated log messages
* caplog.text            -> string containing formatted log output
* caplog.records         -> list of logging.LogRecord instances
* caplog.record_tuples   -> list of (logger_name, level, message) tuples
* caplog.clear()         -> clear captured records and formatted log output string

インスタンスを返します pytest.LogCaptureFixture。

final class LogCaptureFixture[ソース]¶

ログキャプチャへのアクセスと制御を提供します。

property handler: LogCaptureHandler¶: フィクスチャで使用されるロギングハンドラを取得します。

get_records(when)[ソース]¶

可能なテストフェーズのいずれかのログレコードを取得します。

パラメータ:: when (Literal['setup', 'call', 'teardown']) -- どのテストフェーズからレコードを取得するか。有効な値は: "setup"、"call"、および "teardown"。
戻り値:: 指定されたステージでキャプチャされたレコードのリスト。
戻り値の型:: list[LogRecord]

Added in version 3.4.

property text: str¶: フォーマットされたログテキスト。

property records: list[LogRecord]¶: ログレコードのリスト。

property record_tuples: list[tuple[str, int, str]]¶

アサーション比較に使用するために意図されたログレコードの簡略版のリスト。

タプルの形式は:

(logger_name, log_level, message)

property messages: list[str]¶

フォーマットされたログメッセージのリスト。

「records」とは異なり、このリストのログメッセージはすべてフォーマットされています。

「text」とは異なり、このリストのログメッセージにはレベル、タイムスタンプなどが付いていないため、正確な比較がより信頼性の高いものになります。

トレースバックやスタック情報 (logging.exception() またはロギング関数への exc_info または stack_info 引数から) は含まれていないことに注意してください。これはハンドラのフォーマッタによって追加されます。

Added in version 3.7.

clear()[ソース]¶

ログレコードのリストとキャプチャされたログテキストをリセットします。

set_level(level, logger=None)[ソース]¶

テストの期間中にロガーのしきい値レベルを設定します。

このレベルよりも重大度の低いロギングメッセージはキャプチャされません。

バージョン 3.4 で変更: この関数によって変更されたロガーのレベルは、テストの終了時に元の値に戻されます。

要求されたロギングレベルが logging.disable() によって無効にされていた場合、それを有効にします。

パラメータ:

level (int | str) -- レベル。
logger (str | None) -- 更新するロガー。指定されていない場合は、ルートロガー。

with at_level(level, logger=None)[ソース]¶

ログのキャプチャのためのレベルを設定するコンテキストマネージャ。 'with' ステートメントの終了後、レベルは元の値に戻されます。

要求されたロギングレベルが logging.disable() によって無効にされていた場合、それを有効にします。

パラメータ:

level (int | str) -- レベル。
logger (str | None) -- 更新するロガー。指定されていない場合は、ルートロガー。

with filtering(filter_)[ソース]¶

指定されたフィルタを caplog の handler() に一時的に追加し、ブロックの終了時にそのフィルタを削除するコンテキストマネージャ。

パラメータ:: filter -- カスタム logging.Filter オブジェクト。

Added in version 7.5.

capsys¶

チュートリアル: stdout/stderr 出力をキャプチャする方法

capsys()[ソース]¶

sys.stdout と sys.stderr への書き込みのテキストキャプチャを有効にします。

キャプチャされた出力は capsys.readouterr() メソッド呼び出しを通じて利用可能で、(out, err) の名前付きタプルを返します。 out と err は text オブジェクトになります。

インスタンスを返します CaptureFixture[str]。

例:

def test_output(capsys):
    print("hello")
    captured = capsys.readouterr()
    assert captured.out == "hello\n"

class CaptureFixture[ソース]¶

オブジェクトを返します capsys、capsysbinary、capfd、および capfdbinary フィクスチャ。

readouterr()[ソース]¶

キャプチャされた出力を読み取り、内部バッファをリセットします。

戻り値:: out と err の文字列属性を持つ名前付きタプルとしてキャプチャされた内容。
戻り値の型:: CaptureResult

with disabled()[ソース]¶

with ブロック内で一時的にキャプチャを無効にします。

capsysbinary¶

チュートリアル: stdout/stderr 出力をキャプチャする方法

capsysbinary()[ソース]¶

sys.stdout と sys.stderr への書き込みのバイトキャプチャを有効にします。

キャプチャされた出力は capsysbinary.readouterr() メソッド呼び出しを通じて利用可能で、(out, err) の名前付きタプルを返します。 out と err は bytes オブジェクトになります。

インスタンスを返します CaptureFixture[bytes]。

例:

def test_output(capsysbinary):
    print("hello")
    captured = capsysbinary.readouterr()
    assert captured.out == b"hello\n"

config.cache¶

チュートリアル: 失敗したテストを再実行し、テスト実行間で状態を維持する方法

config.cache オブジェクトは、他のプラグインやフィクスチャがテストの実行間で値を保存および取得することを可能にします。フィクスチャからアクセスするには、pytestconfig をフィクスチャに要求し、pytestconfig.cache で取得します。

内部では、キャッシュプラグインは json 標準ライブラリモジュールのシンプルな dumps/loads API を使用します。

config.cache は pytest.Cache のインスタンスです:

final class Cache[ソース]¶

cache フィクスチャのインスタンス。

mkdir(name)[ソース]¶

指定された名前のディレクトリパスオブジェクトを返します。

ディレクトリがまだ存在しない場合は作成されます。これを使用して、テストセッション間でデータベースダンプを保存/取得するためのファイルを管理できます。

Added in version 7.0.

パラメータ:: name (str) -- / セパレータを含まない文字列でなければなりません。名前には他のキャッシュユーザーとの衝突を防ぐためにプラグインまたはアプリケーションの識別子を含めてください。

get(key, default)[ソース]¶

指定されたキーのキャッシュされた値を返します。

まだ値がキャッシュされていない場合、または値を読み取ることができない場合、指定されたデフォルトが返されます。

パラメータ:

key (str) -- / で区切られた値でなければなりません。通常、最初の名前はプラグインまたはアプリケーションの名前です。
default -- キャッシュミスまたは無効なキャッシュ値の場合に返す値。

set(key, value)[ソース]¶

指定されたキーの値を保存します。

パラメータ:

key (str) -- / で区切られた値でなければなりません。通常、最初の名前はプラグインまたはアプリケーションの名前です。
value (object) -- 基本的な Python タイプの任意の組み合わせでなければなりません。リストや辞書のようなネストされたタイプも含まれます。

doctest_namespace¶

チュートリアル: doctest を実行する方法

doctest_namespace()[ソース]¶

フィクスチャは、doctest の名前空間に挿入される dict を返します。

通常、このフィクスチャは別の autouse フィクスチャと組み合わせて使用されます:

@pytest.fixture(autouse=True)
def add_np(doctest_namespace):
    doctest_namespace["np"] = numpy

詳細については: 'doctest_namespace' フィクスチャ。

monkeypatch¶

チュートリアル: モジュールや環境をモンキーパッチ/モックする方法

monkeypatch()[ソース]¶

モンキーパッチのための便利なフィクスチャ。

フィクスチャは、オブジェクト、辞書、または os.environ を変更するためのこれらのメソッドを提供します:

monkeypatch.setattr(obj, name, value, raising=True)
monkeypatch.delattr(obj, name, raising=True)
monkeypatch.setitem(mapping, name, value)
monkeypatch.delitem(obj, name, raising=True)
monkeypatch.setenv(name, value, prepend=None)
monkeypatch.delenv(name, raising=True)
monkeypatch.syspath_prepend(path)
monkeypatch.chdir(path)
monkeypatch.context()

すべての変更は、要求されたテスト関数またはフィクスチャが終了した後に元に戻されます。 raising パラメータは、設定/削除操作が指定されたターゲットを持たない場合に KeyError または AttributeError が発生するかどうかを決定します。

制限されたスコープでフィクスチャによって行われた変更を元に戻すには、context() を使用します。

インスタンスを返します MonkeyPatch。

final class MonkeyPatch[ソース]¶

属性/アイテム/環境変数/シスパスを便利にモンキーパッチするためのヘルパー。

フィクスチャ monkeypatch によって返されます。

バージョン 6.2 で変更: フィクスチャが利用できない場合に pytest.MonkeyPatch() として直接使用することもできます。この場合、with MonkeyPatch.context() as mp: を使用するか、undo() を明示的に呼び出すことを忘れないでください。

classmethod with context()[ソース]¶

with ブロックの終了時に内部で行われたパッチを元に戻す新しい MonkeyPatch オブジェクトを返すコンテキストマネージャ。

例:

import functools


def test_partial(monkeypatch):
    with monkeypatch.context() as m:
        m.setattr(functools, "partial", 3)

テストが終了する前にいくつかのパッチを元に戻す必要がある状況で便利です。例えば、stdlib 関数をモックする場合、モックすると pytest 自体が壊れる可能性があります (この例については #3290 を参照してください)。

setattr(target: str, name: object, value: ~_pytest.monkeypatch.Notset = <notset>, raising: bool = True) → None[ソース]¶

setattr(target: object, name: str, value: object, raising: bool = True) → None

ターゲットの属性値を設定し、古い値を記憶します。

例:

import os

monkeypatch.setattr(os, "getcwd", lambda: "/")

上記のコードは、os.getcwd() 関数を常に "/" を返す lambda に置き換えます。

便利なように、target として文字列を指定することができ、これはドットで区切られたインポートパスとして解釈され、最後の部分が属性名になります:

monkeypatch.setattr("os.getcwd", lambda: "/")

属性が存在しない場合、raising が False に設定されていない限り、AttributeError が発生します。

どこにパッチを当てるか

monkeypatch.setattr は、名前が指すオブジェクトを別のオブジェクトに (一時的に) 変更することで機能します。任意の個々のオブジェクトを指す名前は多数存在する可能性があるため、パッチが機能するためには、テスト対象のシステムが使用する名前をパッチする必要があります。

unittest.mock.patch() 用に書かれていますが、monkeypatch.setattr にも適用される完全な説明については、unittest.mock ドキュメントのセクション Where to patch を参照してください。

delattr(target, name=<notset>, raising=True)[ソース]¶

target から属性 name を削除します。

name が指定されておらず、target が文字列の場合、それはドットで区切られたインポートパスとして解釈され、最後の部分が属性名になります。

属性が存在しない場合、raising が False に設定されていない限り、AttributeError が発生します。

setitem(dic, name, value)[ソース]¶

辞書エントリ name に値を設定します。

delitem(dic, name, raising=True)[ソース]¶

辞書から name を削除します。

存在しない場合、raising が False に設定されていない限り、KeyError が発生します。

setenv(name, value, prepend=None)[ソース]¶

環境変数 name に value を設定します。

prepend が文字の場合、現在の環境変数の値を読み取り、prepend 文字で結合された value を前に追加します。

delenv(name, raising=True)[ソース]¶

環境から name を削除します。

存在しない場合、raising が False に設定されていない限り、KeyError が発生します。

syspath_prepend(path)[ソース]¶

インポート場所の sys.path リストに path を前に追加します。

chdir(path)[ソース]¶

現在の作業ディレクトリを指定されたパスに変更します。

パラメータ:: path (str | PathLike[str]) -- 変更するパス。

undo()[ソース]¶

以前の変更を元に戻します。

この呼び出しは元に戻すスタックを消費します。元に戻す呼び出しの後にさらにモンキーパッチを行わない限り、2 回目の呼び出しは効果がありません。

通常、undo() を呼び出す必要はありません。ティアダウン中に自動的に呼び出されます。

注釈

同じ monkeypatch フィクスチャが単一のテスト関数呼び出し全体で使用されます。テスト関数自体とテストフィクスチャの両方で monkeypatch が使用される場合、undo() を呼び出すと、両方の関数で行われたすべての変更が元に戻されます。

代わりに context() を使用することをお勧めします。

pytestconfig¶

pytestconfig()[ソース]¶

セッションの pytest.Config オブジェクトを返すセッションスコープのフィクスチャ。

例:

def test_foo(pytestconfig):
    if pytestconfig.get_verbosity() > 0:
        ...

pytester¶

Added in version 6.2.

pytest 自体を実行およびテストするために使用できる Pytester インスタンスを提供します。

pytest を隔離して実行できる空のディレクトリを提供し、テスト、設定ファイルの作成、および予想される出力との一致を行うための機能を含みます。

使用するには、最上位の conftest.py ファイルに含めます:

pytest_plugins = "pytester"

final class Pytester[ソース]¶

pytest プラグインのブラックボックステストに最適な、テスト/設定ファイルの作成、pytest の隔離実行、および予想される出力との一致を行うための機能。

外部要因からテスト実行をできるだけ隔離し、初期化中に現在の作業ディレクトリを path に変更し、環境変数を変更します。

exception TimeoutExpired[ソース]¶

plugins: list[str | object]¶: プラグインを使用するためのリスト parseconfig() および runpytest()。初期状態ではこれは空のリストですが、プラグインをリストに追加できます。使用するメソッドによって追加するアイテムのタイプが異なるため、詳細についてはそれらを参照してください。

property path: Path¶: ファイル/テストの作成に使用される一時ディレクトリパスなど。

make_hook_recorder(pluginmanager)[ソース]¶

PytestPluginManager のための新しい HookRecorder を作成します。

chdir()[ソース]¶

一時ディレクトリに移動します。

これはインスタンス化時に自動的に行われます。

makefile(ext, *args, **kwargs)[ソース]¶

テストディレクトリに新しいテキストファイルを作成します。

パラメータ:

ext (str) -- ファイルが使用する拡張子 (ドットを含む)、例: .py。
args (str) -- すべての引数は文字列として扱われ、改行で結合されます。結果はファイルの内容として書き込まれます。ファイルの名前はこのフィクスチャを要求するテスト関数に基づいています。
kwargs (str) -- 各キーワードはファイルの名前であり、その値がファイルの内容として書き込まれます。

戻り値:

最初に作成されたファイル。

戻り値の型:

Path

例:

pytester.makefile(".txt", "line1", "line2")

pytester.makefile(".ini", pytest="[pytest]\naddopts=-rs\n")

バイナリファイルを作成するには、pathlib.Path.write_bytes() を直接使用します:

filename = pytester.path.joinpath("foo.bin")
filename.write_bytes(b"...")

makeconftest(source)[ソース]¶

conftest.py ファイルを書き込みます。

パラメータ:: source (str) -- 内容。
戻り値:: conftest.py ファイル。
戻り値の型:: Path

makeini(source)[ソース]¶

tox.ini ファイルを書き込みます。

パラメータ:: source (str) -- 内容。
戻り値:: tox.ini ファイル。
戻り値の型:: Path

getinicfg(source)[ソース]¶

tox.ini 設定ファイルから pytest セクションを返します。

makepyprojecttoml(source)[ソース]¶

pyproject.toml ファイルを書き込みます。

パラメータ:: source (str) -- 内容。
戻り値:: pyproject.ini ファイル。
戻り値の型:: Path

Added in version 6.0.

makepyfile(*args, **kwargs)[ソース]¶

.py 拡張子を持つ .makefile() のショートカット。

デフォルトでは、拡張子 '.py' を持つテスト名 (例: test_foobar.py) になり、既存のファイルを上書きします。

例:

def test_something(pytester):
    # Initial file is created test_something.py.
    pytester.makepyfile("foobar")
    # To create multiple files, pass kwargs accordingly.
    pytester.makepyfile(custom="foobar")
    # At this point, both 'test_something.py' & 'custom.py' exist in the test directory.

maketxtfile(*args, **kwargs)[ソース]¶

.txt 拡張子を持つ .makefile() のショートカット。

デフォルトでは、拡張子 '.txt' を持つテスト名 (例: test_foobar.txt) になり、既存のファイルを上書きします。

例:

def test_something(pytester):
    # Initial file is created test_something.txt.
    pytester.maketxtfile("foobar")
    # To create multiple files, pass kwargs accordingly.
    pytester.maketxtfile(custom="foobar")
    # At this point, both 'test_something.txt' & 'custom.txt' exist in the test directory.

syspathinsert(path=None)[ソース]¶

ディレクトリを sys.path に前に追加します。デフォルトは path。

これは各テストの終了時にこのオブジェクトが破棄されると自動的に元に戻されます。

パラメータ:: path (str | PathLike[str] | None) -- パス。

mkdir(name)[ソース]¶

新しい (サブ) ディレクトリを作成します。

パラメータ:: name (str | PathLike[str]) -- pytester パスに対するディレクトリの名前。
戻り値:: 作成されたディレクトリ。
戻り値の型:: pathlib.Path

mkpydir(name)[ソース]¶

新しい Python パッケージを作成します。

これにより、空の __init__.py ファイルを持つ (サブ) ディレクトリが作成され、Python パッケージとして認識されます。

copy_example(name=None)[ソース]¶

プロジェクトのディレクトリからテストディレクトリにファイルをコピーします。

パラメータ:: name (str | None) -- コピーするファイルの名前。
戻り値:: コピーされたディレクトリへのパス (self.path 内)。
戻り値の型:: pathlib.Path

getnode(config, arg)[ソース]¶

ファイルのコレクションノードを取得します。

パラメータ:

config (Config) -- pytest 設定。作成方法については parseconfig() および parseconfigure() を参照してください。
arg (str | PathLike[str]) -- ファイルへのパス。

戻り値:

ノード。

戻り値の型:

Collector | Item

getpathnode(path)[ソース]¶

ファイルのコレクションノードを返します。

これは getnode() に似ていますが、(設定された) pytest Config インスタンスを作成するために parseconfigure() を使用します。

パラメータ:: path (str | PathLike[str]) -- ファイルへのパス。
戻り値:: ノード。
戻り値の型:: Collector | Item

genitems(colitems)[ソース]¶

コレクションノードからすべてのテストアイテムを生成します。

これによりコレクションノードが再帰的に処理され、その中に含まれるすべてのテストアイテムのリストが返されます。

パラメータ:: colitems (Sequence[Item | Collector]) -- コレクションノード。
戻り値:: 収集されたアイテム。
戻り値の型:: list[Item]

runitem(source)[ソース]¶

"test_func" アイテムを実行します。

呼び出し元のテストインスタンス (テストメソッドを含むクラス) は、単一のアイテムのテストプロトコルを実行できるランナーを返す .getrunner() メソッドを提供する必要があります。例: _pytest.runner.runtestprotocol。

inline_runsource(source, *cmdlineargs)[ソース]¶

pytest.main() を使用してプロセス内でテストモジュールを実行します。

この実行は "source" を一時ファイルに書き込み、pytest.main() を実行し、その結果の HookRecorder インスタンスを返します。

パラメータ:

source (str) -- テストモジュールのソースコード。
cmdlineargs -- 使用する追加のコマンドライン引数。

inline_genitems(*args)[ソース]¶

プロセス内で pytest.main(['--collect-only']) を実行します。

inline_run() のように、テストプロセス内で pytest 全体を実行するために pytest.main() 関数を実行しますが、収集されたアイテムのタプルと HookRecorder インスタンスを返します。

inline_run(*args, plugins=(), no_reraise_ctrlc=False)[ソース]¶

プロセス内で pytest.main() を実行し、HookRecorder を返します。

pytest.main() 関数を実行して、テストプロセス内で pytest 全体を実行します。これにより、HookRecorder インスタンスが返され、その実行からの結果が runpytest() からの stdout/stderr の一致よりも詳細になります。

パラメータ:

args (str | PathLike[str]) -- コマンドライン引数を pytest.main() に渡します。
plugins -- pytest.main() インスタンスが使用する追加のプラグインインスタンス。
no_reraise_ctrlc (bool) -- 通常、子プロセスの実行からキーボード割り込みを再発生させます。 True の場合、KeyboardInterrupt 例外がキャプチャされます。

runpytest_inprocess(*args, **kwargs)[ソース]¶

pytest をプロセス内で実行した結果を返し、self.runpytest() が提供するインターフェースに似ています。

runpytest(*args, **kwargs)[ソース]¶

コマンドラインオプション "--runpytest" に応じて、pytest をインラインまたはサブプロセスで実行し、RunResult を返します。

parseconfig(*args)[ソース]¶

指定されたコマンドライン引数から新しい pytest pytest.Config インスタンスを返します。

これにより、_pytest.config の pytest ブートストラップコードが呼び出され、新しい pytest.PytestPluginManager が作成され、pytest_cmdline_parse フックが呼び出されて新しい pytest.Config インスタンスが作成されます。

plugins が設定されている場合、それらはプラグインマネージャーに登録されるプラグインモジュールである必要があります。

parseconfigure(*args)[ソース]¶

新しい pytest 設定済み Config インスタンスを返します。

parseconfig() のように新しい pytest.Config インスタンスを返しますが、pytest_configure フックも呼び出します。

getitem(source, funcname='test_func')[ソース]¶

テスト関数のテストアイテムを返します。

ソースを Python ファイルに書き込み、結果のモジュールで pytest のコレクションを実行し、要求された関数名のテストアイテムを返します。

パラメータ:

source (str | PathLike[str]) -- モジュールソース。
funcname (str) -- テストアイテムを返すテスト関数の名前。

戻り値:

テストアイテム。

戻り値の型:

Item

getitems(source)[ソース]¶

モジュールから収集されたすべてのテストアイテムを返します。

ソースを Python ファイルに書き込み、結果のモジュールで pytest のコレクションを実行し、その中に含まれるすべてのテストアイテムを返します。

getmodulecol(source, configargs=(), *, withinit=False)[ソース]¶

source のモジュールコレクションノードを返します。

source を makepyfile() を使用してファイルに書き込み、その後 pytest のコレクションを実行し、テストモジュールのコレクションノードを返します。

パラメータ:

source (str | PathLike[str]) -- 収集するモジュールのソースコード。
configargs -- parseconfigure() に渡す追加の引数。
withinit (bool) -- パッケージであることを保証するために、同じディレクトリに __init__.py ファイルも書き込むかどうか。

collect_by_name(modcol, name)[ソース]¶

モジュールコレクションから名前のコレクションノードを返します。

指定された名前に一致するコレクションノードをモジュールコレクションノードから検索します。

パラメータ:

modcol (Collector) -- モジュールコレクションノード; getmodulecol() を参照してください。
name (str) -- 返すノードの名前。

popen(cmdargs, stdout=-1, stderr=-1, stdin=NotSetType.token, **kw)[ソース]¶

subprocess.Popen を呼び出します。

現在の作業ディレクトリが PYTHONPATH に含まれていることを確認して subprocess.Popen を呼び出します。

代わりに run() を使用することをお勧めします。

run(*cmdargs, timeout=None, stdin=NotSetType.token)[ソース]¶

引数付きでコマンドを実行します。

subprocess.Popen を使用してプロセスを実行し、stdout と stderr を保存します。

パラメータ:

cmdargs (str | PathLike[str]) -- subprocess.Popen に渡す引数のシーケンス。パスのようなオブジェクトは自動的に str に変換されます。
timeout (float | None) -- タイムアウト後に Pytester.TimeoutExpired を発生させる秒数。
stdin (_pytest.compat.NotSetType | bytes | IO[Any] | int) -- オプションの標準入力。 - CLOSE_STDIN (デフォルト) の場合、このメソッドは stdin=subprocess.PIPE で subprocess.Popen を呼び出し、新しいコマンドが開始された直後に標準入力を閉じます。 - bytes 型の場合、これらのバイトがコマンドの標準入力に送信されます。 - それ以外の場合は、subprocess.Popen に渡されます。この場合の詳細については、subprocess.Popen の stdin パラメータのドキュメントを参照してください。

戻り値:

結果。

戻り値の型:

RunResult

runpython(script)[ソース]¶

sys.executable をインタープリターとして使用して Python スクリプトを実行します。

runpython_c(command)[ソース]¶

python -c "command" を実行します。

runpytest_subprocess(*args, timeout=None)[ソース]¶

指定された引数で pytest をサブプロセスとして実行します。

plugins リストに追加されたプラグインは、-p コマンドラインオプションを使用して追加されます。さらに、--basetemp を使用して、一時ファイルやディレクトリを "runpytest-" というプレフィックスが付いた番号付きディレクトリに配置し、通常の番号付き pytest の一時ファイルやディレクトリの場所と競合しないようにします。

パラメータ:

args (str | PathLike[str]) -- pytest サブプロセスに渡す引数のシーケンス。
timeout (float | None) -- タイムアウト後に Pytester.TimeoutExpired を発生させる秒数。

戻り値:

結果。

戻り値の型:

RunResult

spawn_pytest(string, expect_timeout=10.0)[ソース]¶

pexpect を使用して pytest を実行します。

これにより、正しい pytest を使用し、一時ディレクトリの場所を設定します。

pexpect の子プロセスが返されます。

spawn(cmd, expect_timeout=10.0)[ソース]¶

pexpect を使用してコマンドを実行します。

pexpect の子プロセスが返されます。

final class RunResult[ソース]¶

Pytester からコマンドを実行した結果。

ret: int | ExitCode¶: 戻り値。

outlines¶: stdout からキャプチャされた行のリスト。

errlines¶: stderr からキャプチャされた行のリスト。

stdout¶

stdout の LineMatcher。

例として str(stdout) を使用して stdout を再構築するか、一般的に使用される stdout.fnmatch_lines() メソッドを使用します。

stderr¶: stderr の LineMatcher。

duration¶: 秒単位の期間。

parseoutcomes()[ソース]¶

テストプロセスが生成したターミナル出力を解析して、結果の名詞 -> カウントの辞書を返します。

返される名詞は常に複数形になります:

======= 1 failed, 1 passed, 1 warning, 1 error in 0.13s ====

{"failed": 1, "passed": 1, "warnings": 1, "errors": 1} を返します。

classmethod parse_summary_nouns(lines)[ソース]¶

pytest のターミナルサマリー行から名詞を抽出します。

一貫性のために常に複数形の名詞を返します:

======= 1 failed, 1 passed, 1 warning, 1 error in 0.13s ====

{"failed": 1, "passed": 1, "warnings": 1, "errors": 1} を返します。

assert_outcomes(passed=0, skipped=0, failed=0, errors=0, xpassed=0, xfailed=0, warnings=None, deselected=None)[ソース]¶

指定された結果がテスト実行のテキスト出力にそれぞれの数で表示されることをアサートします (0 は発生しなかったことを意味します)。

warnings と deselected は None でない場合にのみチェックされます。

class LineMatcher[ソース]¶

テキストの柔軟なマッチング。

これは、コマンドの出力のような大きなテキストをテストするための便利なクラスです。

コンストラクタは、末尾の改行を含まない行のリストを受け取ります。すなわち、text.splitlines()。

__str__()[ソース]¶

元のテキスト全体を返します。

Added in version 6.2: 古いバージョンでは str() を使用できます。

fnmatch_lines_random(lines2)[ソース]¶

出力内の行が任意の順序で存在することを確認します (using fnmatch.fnmatch())。

re_match_lines_random(lines2)[ソース]¶

出力に任意の順序で行が存在することを確認します（re.match() を使用）。

get_lines_after(fnline)[ソース]¶

テキスト内の指定された行の後に続くすべての行を返します。

指定された行にはグロブワイルドカードを含めることができます。

fnmatch_lines(lines2, *, consecutive=False)[ソース]¶

出力に行が存在することを確認します（fnmatch.fnmatch() を使用）。

引数は一致する必要がある行のリストで、グロブワイルドカードを使用できます。一致しない場合は pytest.fail() が呼び出されます。一致と不一致はエラーメッセージの一部としても表示されます。

パラメータ:

lines2 (Sequence[str]) -- 一致する文字列パターン。
consecutive (bool) -- 行を連続して一致させますか？

re_match_lines(lines2, *, consecutive=False)[ソース]¶

出力に行が存在することを確認します（re.match() を使用）。

引数は re.match を使用して一致する必要がある行のリストです。一致しない場合は pytest.fail() が呼び出されます。

一致と不一致はエラーメッセージの一部としても表示されます。

パラメータ:

lines2 (Sequence[str]) -- 一致する文字列パターン。
consecutive (bool) -- 行を連続して一致させますか？

no_fnmatch_line(pat)[ソース]¶

fnmatch.fnmatch を使用して、キャプチャされた行が指定されたパターンに一致しないことを確認します。

パラメータ:: pat (str) -- 行を一致させるパターン。

no_re_match_line(pat)[ソース]¶

re.match を使用して、キャプチャされた行が指定されたパターンに一致しないことを確認します。

パラメータ:: pat (str) -- 行を一致させる正規表現。

str()[ソース]¶

元のテキスト全体を返します。

final class HookRecorder[ソース]¶

プラグインマネージャーで呼び出されたすべてのフックを記録します。

フックレコーダーは Pytester によって作成されます。

これはプラグインマネージャー内のすべてのフック呼び出しをラップし、通常の呼び出しを伝播する前に各呼び出しを記録します。

getcalls(names)[ソース]¶

指定された名前（または名前）のフックへのすべての記録された呼び出しを取得します。

matchreport(inamepart='', names=('pytest_runtest_logreport', 'pytest_collectreport'), when=None)[ソース]¶

ドットインポートパスが一致するテストレポートを返します。

final class RecordedHookCall[ソース]¶

フックへの記録された呼び出し。

フック呼び出しの引数は属性として設定されます。例えば：

calls = hook_recorder.getcalls("pytest_runtest_setup")
# Suppose pytest_runtest_setup was called once with `item=an_item`.
assert calls[0].item is an_item

record_property¶

チュートリアル： record_property

record_property()[ソース]¶

呼び出しテストに追加のプロパティを追加します。

ユーザープロパティはテストレポートの一部となり、JUnit XML のような設定されたレポーターで利用可能です。

フィクスチャは name, value で呼び出し可能です。値は自動的に XML エンコードされます。

例:

def test_function(record_property):
    record_property("example_key", 1)

record_testsuite_property¶

チュートリアル： record_testsuite_property

record_testsuite_property()[ソース]¶

新しい <property> タグをルート <testsuite> の子として記録します。

これはテストスイート全体に関するグローバル情報の記録に適しており、xunit2 JUnit ファミリーと互換性があります。

これは session スコープのフィクスチャで、(name, value) で呼び出されます。例：

def test_foo(record_testsuite_property):
    record_testsuite_property("ARCH", "PPC")
    record_testsuite_property("STORAGE_TYPE", "CEPH")

パラメータ:

name -- プロパティ名。
value -- プロパティ値。文字列に変換されます。

警告

現在、このフィクスチャは pytest-xdist プラグインでは 動作しません。詳細は #7767 を参照してください。

recwarn¶

チュートリアル：警告の記録

recwarn()[ソース]¶

WarningsRecorder インスタンスを返し、テスト関数によって発行されたすべての警告を記録します。

警告カテゴリに関する情報は警告をキャプチャする方法を参照してください。

class WarningsRecorder[ソース]¶

警告を記録するためのコンテキストマネージャー。

記録された各警告は warnings.WarningMessage のインスタンスです。

Adapted from warnings.catch_warnings.

注釈

DeprecationWarning と PendingDeprecationWarning は異なる扱いを受けます。詳細はコードが非推奨警告をトリガーすることを確認するを参照してください。

property list: list[WarningMessage]¶: 記録された警告のリスト。

__getitem__(i)[ソース]¶

インデックスで記録された警告を取得します。

__iter__()[ソース]¶

記録された警告を反復処理します。

__len__()[ソース]¶

記録された警告の数。

pop(cls=<class 'Warning'>)[ソース]¶

Pop the first recorded warning which is an instance of cls, but not an instance of a child class of any other match. Raises AssertionError if there is no match.

clear()[ソース]¶

記録された警告のリストをクリアします。

request¶

例：コマンドラインオプションに応じて異なる値をテスト関数に渡す

request フィクスチャは、要求されたテスト関数の情報を提供する特別なフィクスチャです。

class FixtureRequest[ソース]¶

request フィクスチャのタイプ。

リクエストオブジェクトは、要求されたテストコンテキストへのアクセスを提供し、フィクスチャがパラメータ化されている場合は param 属性を持ちます。

fixturename: Final¶: このリクエストが実行されているフィクスチャ。

property scope: Literal['session', 'package', 'module', 'class', 'function']¶: スコープ文字列。 "function"、"class"、"module"、"package"、"session" のいずれか。

property fixturenames: list[str]¶: このリクエスト内のすべてのアクティブなフィクスチャの名前。

abstract property node¶: 基礎となるコレクションノード（現在のリクエストスコープに依存）。

property config: Config¶: このリクエストに関連付けられた pytest 設定オブジェクト。

property function¶: リクエストが関数ごとのスコープを持つ場合のテスト関数オブジェクト。

property cls¶: テスト関数が収集されたクラス（None の場合があります）。

property instance¶: テスト関数が収集されたインスタンス（None の場合があります）。

property module¶: テスト関数が収集された Python モジュールオブジェクト。

property path: Path¶: テスト関数が収集されたパス。

property keywords: MutableMapping[str, Any]¶: 基礎となるノードのキーワード/マーカー辞書。

property session: Session¶: Pytest セッションオブジェクト。

abstractmethod addfinalizer(finalizer)[ソース]¶

要求されたテストコンテキスト内の最後のテストが実行を終了した後に引数なしで呼び出されるファイナライザ/ティアダウン関数を追加します。

applymarker(marker)[ソース]¶

単一のテスト関数の呼び出しにマーカーを適用します。

このメソッドは、すべての関数呼び出しにキーワード/マーカーを持たせたくない場合に便利です。

パラメータ:: marker (str | MarkDecorator) -- pytest.mark.NAME(...) の呼び出しによって作成されたオブジェクト。

raiseerror(msg)[ソース]¶

FixtureLookupError 例外を発生させます。

パラメータ:: msg (str | None) -- オプションのカスタムエラーメッセージ。

getfixturevalue(argname)[ソース]¶

名前付きフィクスチャ関数を動的に実行します。

可能な場合は、関数引数を介してフィクスチャを宣言することをお勧めします。しかし、テストセットアップ時に別のフィクスチャを使用するかどうかを決定する場合は、この関数を使用してフィクスチャまたはテスト関数本体内でそれを取得できます。

このメソッドはテストセットアップフェーズまたはテスト実行フェーズ中に使用できますが、テストティアダウンフェーズ中にはフィクスチャの値が利用できない場合があります。

パラメータ:: argname (str) -- フィクスチャ名。
例外:: pytest.FixtureLookupError -- 指定されたフィクスチャが見つからなかった場合。

testdir¶

pytester と同じですが、メソッドが適用可能な場合にレガシー py.path.local オブジェクトを返すインスタンスを提供します。

新しいコードでは、testdir の使用を避け、pytester を使用することをお勧めします。

final class Testdir[ソース]

Pytester に似ていますが、このクラスはレガシー legacy_path オブジェクトで動作します。

すべてのメソッドは内部の Pytester インスタンスに転送され、必要に応じて結果を legacy_path オブジェクトに変換します。

exception TimeoutExpired

property tmpdir: LocalPath: テストが実行される一時ディレクトリ。

make_hook_recorder(pluginmanager)[ソース]

Pytester.make_hook_recorder() を参照してください。

chdir()[ソース]

Pytester.chdir() を参照してください。

makefile(ext, *args, **kwargs)[ソース]

Pytester.makefile() を参照してください。

makeconftest(source)[ソース]

Pytester.makeconftest() を参照してください。

makeini(source)[ソース]

Pytester.makeini() を参照してください。

getinicfg(source)[ソース]

Pytester.getinicfg() を参照してください。

makepyprojecttoml(source)[ソース]

Pytester.makepyprojecttoml() を参照してください。

makepyfile(*args, **kwargs)[ソース]

Pytester.makepyfile() を参照してください。

maketxtfile(*args, **kwargs)[ソース]

Pytester.maketxtfile() を参照してください。

syspathinsert(path=None)[ソース]

Pytester.syspathinsert() を参照してください。

mkdir(name)[ソース]

Pytester.mkdir() を参照してください。

mkpydir(name)[ソース]

Pytester.mkpydir() を参照してください。

copy_example(name=None)[ソース]

Pytester.copy_example() を参照してください。

getnode(config, arg)[ソース]

Pytester.getnode() を参照してください。

getpathnode(path)[ソース]: Pytester.getpathnode() を参照してください。

genitems(colitems)[ソース]

Pytester.genitems() を参照してください。

runitem(source)[ソース]: Pytester.runitem() を参照してください。

inline_runsource(source, *cmdlineargs)[ソース]: Pytester.inline_runsource() を参照してください。

inline_genitems(*args)[ソース]: Pytester.inline_genitems() を参照してください。

inline_run(*args, plugins=(), no_reraise_ctrlc=False)[ソース]

Pytester.inline_run() を参照してください。

runpytest_inprocess(*args, **kwargs)[ソース]

Pytester.runpytest_inprocess() を参照してください。

runpytest(*args, **kwargs)[ソース]

Pytester.runpytest() を参照してください。

parseconfig(*args)[ソース]

Pytester.parseconfig() を参照してください。

parseconfigure(*args)[ソース]

Pytester.parseconfigure() を参照してください。

getitem(source, funcname='test_func')[ソース]: Pytester.getitem() を参照してください。

getitems(source)[ソース]: Pytester.getitems() を参照してください。

getmodulecol(source, configargs=(), withinit=False)[ソース]: Pytester.getmodulecol() を参照してください。

collect_by_name(modcol, name)[ソース]

Pytester.collect_by_name() を参照してください。

popen(cmdargs, stdout=-1, stderr=-1, stdin=NotSetType.token, **kw)[ソース]: Pytester.popen() を参照してください。

run(*cmdargs, timeout=None, stdin=NotSetType.token)[ソース]

Pytester.run() を参照してください。

runpython(script)[ソース]

Pytester.runpython() を参照してください。

runpython_c(command)[ソース]: Pytester.runpython_c() を参照してください。

runpytest_subprocess(*args, timeout=None)[ソース]

Pytester.runpytest_subprocess() を参照してください。

spawn_pytest(string, expect_timeout=10.0)[ソース]

Pytester.spawn_pytest() を参照してください。

spawn(cmd, expect_timeout=10.0)[ソース]

Pytester.spawn() を参照してください。

tmp_path¶

チュートリアル：テストで一時ディレクトリとファイルを使用する方法

tmp_path()[ソース]¶

一時ディレクトリ（pathlib.Path オブジェクトとして）を返します。これは各テスト関数の呼び出しに固有です。一時ディレクトリは、基本一時ディレクトリのサブディレクトリとして作成され、保持期間は一時ディレクトリの場所と保持で説明されているように設定可能です。

tmp_path_factory¶

チュートリアル： tmp_path_factory フィクスチャ

tmp_path_factory は TempPathFactory のインスタンスです：

final class TempPathFactory[ソース]¶

共通の基本一時ディレクトリの下に一時ディレクトリを作成するファクトリ。詳細は一時ディレクトリの場所と保持を参照してください。

mktemp(basename, numbered=True)[ソース]¶

ファクトリによって管理される新しい一時ディレクトリを作成します。

パラメータ:

basename (str) -- ディレクトリの基本名。相対パスでなければなりません。
numbered (bool) -- True の場合、番号付きサフィックスを追加してディレクトリが一意であることを確認します。既存のものより大きい番号を追加します。 basename="foo-" と numbered=True は、この関数が "foo-0"、"foo-1"、"foo-2" などのディレクトリを作成することを意味します。

戻り値:

新しいディレクトリへのパス。

戻り値の型:

Path

getbasetemp()[ソース]¶

基本一時ディレクトリを返し、必要に応じて作成します。

戻り値:: 基本一時ディレクトリ。
戻り値の型:: Path

tmpdir¶

チュートリアル： tmpdir および tmpdir_factory フィクスチャ

tmpdir()¶

一時ディレクトリ（legacy_path オブジェクトとして）を返します。これは各テスト関数の呼び出しに固有です。一時ディレクトリは、基本一時ディレクトリのサブディレクトリとして作成され、保持期間は一時ディレクトリの場所と保持で説明されているように設定可能です。

注釈

最近では、tmp_path を使用することが推奨されます。

About the tmpdir and tmpdir_factory fixtures。

tmpdir_factory¶

チュートリアル： tmpdir および tmpdir_factory フィクスチャ

tmpdir_factory は TempdirFactory のインスタンスです：

final class TempdirFactory[ソース]¶

後方互換性のためのラッパーで、TempPathFactory に対して py.path.local を実装します。

注釈

最近では、tmp_path_factory を使用することが推奨されます。

About the tmpdir and tmpdir_factory fixtures。

mktemp(basename, numbered=True)[ソース]¶

TempPathFactory.mktemp() と同じですが、py.path.local オブジェクトを返します。

getbasetemp()[ソース]¶

TempPathFactory.getbasetemp() と同じですが、py.path.local オブジェクトを返します。

フック¶

チュートリアル：プラグインの作成

Reference to all hooks which can be implemented by conftest.py files and plugins.

@pytest.hookimpl¶

@pytest.hookimpl¶

フック実装として関数をマークするための pytest のデコレーター。

フック関数の記述および pluggy.HookimplMarker() を参照してください。

@pytest.hookspec¶

@pytest.hookspec¶

フックスペックとして関数をマークするための pytest のデコレーター。

新しいフックの宣言および pluggy.HookspecMarker() を参照してください。

ブートストラップフック¶

早期に登録されたプラグイン（内部およびサードパーティプラグイン）に対して呼び出されるブートストラップフック。

pytest_load_initial_conftests(early_config, parser, args)[ソース]¶

コマンドラインオプションの解析に先立って、initial conftest files の読み込みを実装するために呼び出されます。

パラメータ:

early_config (Config) -- pytest 設定オブジェクト。
args (list[str]) -- コマンドラインで渡された引数。
parser (Parser) -- コマンドラインオプションを追加するため。

conftest プラグインで使用する¶

conftest ファイルに対してはこのフックは呼び出されません。

pytest_cmdline_parse(pluginmanager, args)[ソース]¶

指定された引数を解析して初期化された Config を返します。

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

注釈

このフックは、pytest.main を使用してインプロセステストを実行する際に plugins 引数に渡されたプラグインクラスに対してのみ呼び出されます。

パラメータ:

pluginmanager (PytestPluginManager) -- pytest プラグインマネージャー。
args (list[str]) -- コマンドラインで渡された引数のリスト。

戻り値:

pytest 設定オブジェクト。

戻り値の型:

Config | None

conftest プラグインで使用する¶

conftest ファイルに対してはこのフックは呼び出されません。

pytest_cmdline_main(config)[ソース]¶

メインのコマンドラインアクションを実行するために呼び出されます。

デフォルトの実装は、configure フックと pytest_runtestloop を呼び出します。

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

パラメータ:: config (Config) -- pytest 設定オブジェクト。
戻り値:: 終了コード。
戻り値の型:: ExitCode | int | None

conftest プラグインで使用する¶

このフックは initial conftests に対してのみ呼び出されます。

初期化フック¶

プラグインおよび conftest.py ファイルに対して呼び出される初期化フック。

pytest_addoption(parser, pluginmanager)[ソース]¶

argparse スタイルのオプションと ini スタイルの設定値を登録します。テスト実行の開始時に一度だけ呼び出されます。

パラメータ:

parser (Parser) -- コマンドラインオプションを追加するには、parser.addoption(...) を呼び出します。 ini ファイルの値を追加するには、parser.addini(...) を呼び出します。
pluginmanager (PytestPluginManager) -- pytest プラグインマネージャー。これを使用して hookspec() や hookimpl() をインストールし、あるプラグインが別のプラグインのフックを呼び出してコマンドラインオプションの追加方法を変更できるようにします。

オプションは後で config オブジェクトを介してアクセスできます。

config.getoption(name) を使用してコマンドラインオプションの値を取得します。
config.getini(name) を使用して ini スタイルのファイルから読み取った値を取得します。

設定オブジェクトは、多くの内部オブジェクトに .config 属性を介して渡されるか、pytestconfig フィクスチャとして取得できます。

注釈

このフックはフックラッパーと互換性がありません。

conftest プラグインで使用する¶

conftest プラグインがこのフックを実装している場合、conftest が登録されたときにすぐに呼び出されます。

このフックは initial conftests に対してのみ呼び出されます。

pytest_addhooks(pluginmanager)[ソース]¶

プラグイン登録時に呼び出され、pluginmanager.add_hookspecs(module_or_class, prefix) の呼び出しを介して新しいフックを追加できるようにします。

パラメータ:: pluginmanager (PytestPluginManager) -- pytest プラグインマネージャー。

注釈

このフックはフックラッパーと互換性がありません。

conftest プラグインで使用する¶

conftest プラグインがこのフックを実装している場合、conftest が登録されたときにすぐに呼び出されます。

pytest_configure(config)[ソース]¶

プラグインおよび conftest ファイルが初期設定を実行できるようにします。

注釈

このフックはフックラッパーと互換性がありません。

パラメータ:: config (Config) -- pytest 設定オブジェクト。

conftest プラグインで使用する¶

このフックは、コマンドラインオプションが解析された後、すべての initial conftest ファイルに対して呼び出されます。その後、他の conftest ファイルが登録されるときに呼び出されます。

pytest_unconfigure(config)[ソース]¶

テストプロセスが終了する前に呼び出されます。

パラメータ:: config (Config) -- pytest 設定オブジェクト。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。

pytest_sessionstart(session)[ソース]¶

Session オブジェクトが作成された後、コレクションを実行し、テストループに入る前に呼び出されます。

パラメータ:: session (Session) -- pytest セッションオブジェクト。

conftest プラグインで使用する¶

このフックは initial conftests に対してのみ呼び出されます。

pytest_sessionfinish(session, exitstatus)[ソース]¶

テストの全実行が終了した後、終了ステータスをシステムに返す直前に呼び出されます。

パラメータ:

session (Session) -- pytest セッションオブジェクト。
exitstatus (int | ExitCode) -- pytest がシステムに返すステータス。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。

pytest_plugin_registered(plugin, plugin_name, manager)[ソース]¶

新しい pytest プラグインが登録されました。

パラメータ:

plugin (_PluggyPlugin) -- プラグインモジュールまたはインスタンス。
plugin_name (str) -- プラグインが登録された名前。
manager (PytestPluginManager) -- pytest プラグインマネージャー。

注釈

このフックはフックラッパーと互換性がありません。

conftest プラグインで使用する¶

conftest プラグインがこのフックを実装している場合、conftest が登録されたときにすぐに呼び出されます。これまでに登録された各プラグイン（自分自身を含む！）およびその後に登録されるすべてのプラグインに対して呼び出されます。

コレクションフック¶

pytest はファイルおよびディレクトリを収集するために次のフックを呼び出します：

pytest_collection(session)[ソース]¶

指定されたセッションのコレクションフェーズを実行します。

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。戻り値は使用されませんが、さらなる処理を停止します。

デフォルトのコレクションフェーズは次のとおりです（詳細は個々のフックを参照してください）：

初期コレクターとして session から開始：

pytest_collectstart(collector)

report = pytest_make_collect_report(collector)

インタラクティブな例外が発生した場合は pytest_exception_interact(collector, call, report)

収集された各ノードに対して：

アイテムの場合、pytest_itemcollected(item)

コレクターの場合、それに再帰します。

pytest_collectreport(report)

pytest_collection_modifyitems(session, config, items)

選択解除されたアイテムに対して pytest_deselected(items) (複数回呼び出される場合があります)

pytest_collection_finish(session)
session.items を収集されたアイテムのリストに設定します。
session.testscollected を収集されたアイテムの数に設定します。

コレクションの前に何らかのアクションを実行するためにこのフックを実装できます。例えば、ターミナルプラグインはこれを使用してコレクションカウンターの表示を開始します（None を返します）。

パラメータ:: session (Session) -- pytest セッションオブジェクト。

conftest プラグインで使用する¶

このフックは initial conftests に対してのみ呼び出されます。

pytest_ignore_collect(collection_path, path, config)[ソース]¶

このパスをコレクションの対象外にするには True を返します。

他のプラグインがパスをコレクションの対象外にすることを許可するには None を返します。

False を返すと、このパスを強制的にコレクションの対象外にしません。他のプラグインがこのパスを無視する機会を与えません。

このフックは、より具体的なフックを呼び出す前にすべてのファイルとディレクトリに対して参照されます。

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

パラメータ:

collection_path (pathlib.Path) -- 分析するパス。
path (LEGACY_PATH) -- 分析するパス（非推奨）。
config (Config) -- pytest 設定オブジェクト。

バージョン 7.0.0 で変更: collection_path パラメータは、path パラメータの pathlib.Path 相当として追加されました。 path パラメータは非推奨となりました。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。指定されたコレクションパスに対して、コレクションパスの親ディレクトリにある conftest ファイルのみが参照されます（パスがディレクトリの場合、そのディレクトリ自身の conftest ファイルは参照されません。ディレクトリは自分自身を無視できません！）。

pytest_collect_directory(path, parent)[ソース]¶

指定されたディレクトリに対して Collector を作成します。関連性がない場合は None を返します。

Added in version 8.0.

最良の結果を得るために、返されるコレクターは Directory のサブクラスであるべきですが、これは必須ではありません。

新しいノードには指定された parent を親として持つ必要があります。

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

パラメータ:: path (pathlib.Path) -- 分析するパス。

このフックの使用例についてはカスタムディレクトリコレクタの使用を参照してください。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。指定されたコレクションパスに対して、コレクションパスの親ディレクトリにある conftest ファイルのみが参照されます（パスがディレクトリの場合、そのディレクトリ自身の conftest ファイルは参照されません。ディレクトリは自分自身を収集できません！）。

pytest_collect_file(file_path, path, parent)[ソース]¶

指定されたパスに対して Collector を作成します。関連性がない場合は None を返します。

最良の結果を得るために、返されるコレクターは File のサブクラスであるべきですが、これは必須ではありません。

新しいノードには指定された parent を親として持つ必要があります。

パラメータ:

file_path (pathlib.Path) -- 分析するパス。
path (LEGACY_PATH) -- 収集するパス（非推奨）。

バージョン 7.0.0 で変更: file_path パラメータは、path パラメータの pathlib.Path 相当として追加されました。 path パラメータは非推奨となりました。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。指定されたファイルパスに対して、ファイルパスの親ディレクトリにある conftest ファイルのみが参照されます。

pytest_pycollect_makemodule(module_path, path, parent)[ソース]¶

指定されたパスに対して pytest.Module コレクターを返します。関連性がない場合は None を返します。

このフックは、一致する各テストモジュールパスに対して呼び出されます。テストモジュールとして一致しないファイルに対してテストモジュールを作成したい場合は、pytest_collect_file フックを使用する必要があります。

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

パラメータ:

module_path (pathlib.Path) -- 収集するモジュールのパス。
path (LEGACY_PATH) -- 収集するモジュールのパス（非推奨）。

バージョン 7.0.0 で変更: module_path パラメータは、path パラメータの pathlib.Path 相当として追加されました。

path パラメータは fspath に置き換えられました。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。指定された親コレクターに対して、コレクターのディレクトリおよびその親ディレクトリにある conftest ファイルのみが参照されます。

Python モジュール内のオブジェクトのコレクションに影響を与えるために次のフックを使用できます：

pytest_pycollect_makeitem(collector, name, obj)[ソース]¶

モジュール内の Python オブジェクトに対してカスタムアイテム/コレクターを返します。関連性がない場合は None を返します。

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

パラメータ:

collector (Module | Class) -- モジュール/クラスコレクター。
name (str) -- モジュール/クラス内のオブジェクトの名前。
obj (object) -- オブジェクト。

戻り値:

作成されたアイテム/コレクター。

戻り値の型:

None | Item | Collector | list[Item | Collector]

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。指定されたコレクターに対して、コレクターのディレクトリおよびその親ディレクトリにある conftest ファイルのみが参照されます。

pytest_generate_tests(metafunc)[ソース]¶

テスト関数への（複数の）パラメータ化された呼び出しを生成します。

パラメータ:: metafunc (Metafunc) -- テスト関数のための Metafunc ヘルパー。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。指定された関数定義に対して、関数のディレクトリおよびその親ディレクトリにある conftest ファイルのみが参照されます。

pytest_make_parametrize_id(config, val, argname)[ソース]¶

与えられた val のユーザーフレンドリーな文字列表現を返します。これは @pytest.mark.parametrize 呼び出しによって使用されます。フックが val を知らない場合は None を返します。

必要に応じて、パラメータ名は argname として利用可能です。

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

パラメータ:

config (Config) -- pytest 設定オブジェクト。
val (object) -- パラメータ化された値。
argname (str) -- pytest によって生成された自動パラメータ名。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。

テストスキップに影響を与えるためのフック：

pytest_markeval_namespace(config)[ソース]¶

xfail/skipif マーカーの文字列条件を評価するために使用されるグローバル辞書を構築する際に呼び出されます。

マーカーの条件が、コレクション時に取得するのが高価または不可能なオブジェクトを必要とする場合に便利です。これは通常のブール条件によって必要とされます。

Added in version 6.2.

パラメータ:: config (Config) -- pytest 設定オブジェクト。
戻り値:: 追加するグローバルの辞書。
戻り値の型:: dict[str, Any]

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。指定されたアイテムに対して、アイテムの親ディレクトリにある conftest ファイルのみが参照されます。

コレクションが完了した後、アイテムの順序を変更したり、削除したり、テストアイテムを修正したりできます：

pytest_collection_modifyitems(session, config, items)[ソース]¶

コレクションが実行された後に呼び出されます。アイテムをフィルタリングまたはインプレースで再注文することができます。

アイテムが選択解除（items からフィルタリング）された場合、他のプラグインに適切に通知するために、フック pytest_deselected を選択解除されたアイテムで明示的に呼び出す必要があります。例えば、config.hook.pytest_deselected(deselected_items) のように。

パラメータ:

session (Session) -- pytest セッションオブジェクト。
config (Config) -- pytest 設定オブジェクト。
items (list[Item]) -- アイテムオブジェクトのリスト。

conftest プラグインで使用する¶

任意の conftest プラグインがこのフックを実装できます。

注釈

このフックが conftest.py ファイルに実装されている場合、実装されている conftest.py の下にあるアイテムだけでなく、すべての収集されたアイテムを常に受け取ります。

pytest_collection_finish(session)[ソース]¶

コレクションが実行および変更された後に呼び出されます。

パラメータ:: session (Session) -- pytest セッションオブジェクト。

conftest プラグインで使用する¶

任意の conftest プラグインがこのフックを実装できます。

テスト実行（runtest）フック¶

すべての runtest 関連のフックは pytest.Item オブジェクトを受け取ります。

pytest_runtestloop(session)[ソース]¶

メインの runtest ループを実行します（コレクションが終了した後）。

デフォルトのフック実装は、コレクションが失敗した場合や collectonly pytest オプションが設定されている場合を除き、セッションで収集されたすべてのアイテム（session.items）に対して runtest プロトコルを実行します。

任意の時点で pytest.exit() が呼び出された場合、ループは直ちに終了します。

任意の時点で session.shouldfail または session.shouldstop が設定された場合、現在のアイテムの runtest プロトコルが終了した後にループが終了します。

パラメータ:: session (Session) -- pytest セッションオブジェクト。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。

pytest_runtest_protocol(item, nextitem)[ソース]¶

単一のテストアイテムに対して runtest プロトコルを実行します。

デフォルトの runtest プロトコルは次のとおりです（詳細は個々のフックを参照してください）：

pytest_runtest_logstart(nodeid, location)
セットアップフェーズ：
- call = pytest_runtest_setup(item) (CallInfo(when="setup") でラップ)
- report = pytest_runtest_makereport(item, call)
- pytest_runtest_logreport(report)
- インタラクティブな例外が発生した場合は pytest_exception_interact(call, report)
セットアップが成功し、setuponly pytest オプションが設定されていない場合のコールフェーズ：
- call = pytest_runtest_call(item) (CallInfo(when="call") でラップ)
- report = pytest_runtest_makereport(item, call)
- pytest_runtest_logreport(report)
- インタラクティブな例外が発生した場合は pytest_exception_interact(call, report)
ティアダウンフェーズ：
- call = pytest_runtest_teardown(item, nextitem)``（``CallInfo(when="teardown") でラップ）
- report = pytest_runtest_makereport(item, call)
- pytest_runtest_logreport(report)
- インタラクティブな例外が発生した場合は pytest_exception_interact(call, report)
pytest_runtest_logfinish(nodeid, location)

パラメータ:

item (Item) -- runtest プロトコルが実行されるテストアイテム。
nextitem (Item | None) -- 次に予定されているテストアイテム（これが最後の場合は None）。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。

pytest_runtest_logstart(nodeid, location)[ソース]¶

単一のアイテムに対して runtest プロトコルの実行を開始する際に呼び出されます。

runtest プロトコルの説明については pytest_runtest_protocol を参照してください。

パラメータ:

nodeid (str) -- アイテムの完全なノード ID。
location (tuple[str, int | None, str]) -- (filename, lineno, testname) のタプル。 filename は config.rootpath に対する相対ファイルパスであり、lineno は 0 ベースです。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。指定されたアイテムに対して、アイテムのディレクトリおよびその親ディレクトリにある conftest ファイルのみが参照されます。

pytest_runtest_logfinish(nodeid, location)[ソース]¶

単一のアイテムに対して runtest プロトコルの実行を終了する際に呼び出されます。

runtest プロトコルの説明については pytest_runtest_protocol を参照してください。

パラメータ:

nodeid (str) -- アイテムの完全なノード ID。
location (tuple[str, int | None, str]) -- (filename, lineno, testname) のタプル。 filename は config.rootpath に対する相対ファイルパスであり、lineno は 0 ベースです。

conftest プラグインで使用する¶

pytest_runtest_setup(item)[ソース]¶

テストアイテムのセットアップフェーズを実行するために呼び出されます。

デフォルトの実装は、item およびそのすべての親（まだセットアップされていないもの）に対して setup() を実行します。これには、アイテムが必要とするフィクスチャの値を取得すること（まだ取得されていない場合）が含まれます。

パラメータ:: item (Item) -- アイテム。

conftest プラグインで使用する¶

pytest_runtest_call(item)[ソース]¶

テストアイテムのテストを実行するために呼び出されます（コールフェーズ）。

デフォルトの実装は item.runtest() を呼び出します。

パラメータ:: item (Item) -- アイテム。

conftest プラグインで使用する¶

pytest_runtest_teardown(item, nextitem)[ソース]¶

テストアイテムのティアダウンフェーズを実行するために呼び出されます。

デフォルトの実装はファイナライザを実行し、item およびそのすべての親（ティアダウンが必要なもの）に対して teardown() を呼び出します。これには、アイテムが必要とするフィクスチャのティアダウンフェーズの実行（スコープ外になる場合）が含まれます。

パラメータ:

item (Item) -- アイテム。
nextitem (Item | None) -- 次に予定されているテストアイテム（次のテストアイテムが予定されていない場合は None）。この引数は正確なティアダウンを実行するために使用されます。つまり、nextitem がセットアップ関数のみを呼び出す必要があるように、ちょうど十分なファイナライザを呼び出します。

conftest プラグインで使用する¶

pytest_runtest_makereport(item, call)[ソース]¶

各セットアップ、コール、およびティアダウン runtest フェーズに対して TestReport を作成するために呼び出されます。

runtest プロトコルの説明については pytest_runtest_protocol を参照してください。

パラメータ:

item (Item) -- アイテム。
call (CallInfo[None]) -- フェーズの CallInfo。

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

conftest プラグインで使用する¶

これらのフックのデフォルト実装については、_pytest.runner および _pytest.pdb を参照してください。これらは _pytest.capture とその入出力キャプチャと連携して、テスト失敗時にインタラクティブデバッグに直ちに移行します。

pytest_pyfunc_call(pyfuncitem)[ソース]¶

基礎となるテスト関数を呼び出します。

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

パラメータ:: pyfuncitem (Function) -- 関数アイテム。

conftest プラグインで使用する¶

レポートフック¶

セッション関連のレポートフック：

pytest_collectstart(collector)[ソース]¶

コレクターが収集を開始します。

パラメータ:: collector (Collector) -- コレクター。

conftest プラグインで使用する¶

pytest_make_collect_report(collector)[ソース]¶

collector.collect() を実行し、CollectReport を返します。

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

パラメータ:: collector (Collector) -- コレクター。

conftest プラグインで使用する¶

pytest_itemcollected(item)[ソース]¶

テストアイテムを収集しました。

パラメータ:: item (Item) -- アイテム。

conftest プラグインで使用する¶

pytest_collectreport(report)[ソース]¶

コレクターが収集を終了しました。

パラメータ:: report (CollectReport) -- 収集レポート。

conftest プラグインで使用する¶

pytest_deselected(items)[ソース]¶

キーワードなどで選択解除されたテストアイテムに対して呼び出されます。

このフックには、プラグインのための 2 つの統合側面があることに注意してください：

選択解除されたアイテムを通知するために実装できます。
アイテムが選択解除されたときに、他のプラグインに適切に通知するために pytest_collection_modifyitems 実装から 呼び出される 必要があります。

複数回呼び出される場合があります。

パラメータ:: items (Sequence[Item]) -- アイテム。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。

pytest_report_header(config, start_path, startdir)[ソース]¶

ターミナルレポートのヘッダー情報として表示される文字列または文字列のリストを返します。

パラメータ:

config (Config) -- pytest 設定オブジェクト。
start_path (pathlib.Path) -- 開始ディレクトリ。
startdir (LEGACY_PATH) -- 開始ディレクトリ（非推奨）。

注釈

プラグインによって返された行は、それ以前に実行されたプラグインの行の前に表示されます。行を最初に表示したい場合は、trylast=True を使用してください。

バージョン 7.0.0 で変更: start_path パラメータは、startdir パラメータの pathlib.Path 相当として追加されました。 startdir パラメータは非推奨となりました。

conftest プラグインで使用する¶

このフックは initial conftests に対してのみ呼び出されます。

pytest_report_collectionfinish(config, start_path, startdir, items)[ソース]¶

コレクションが正常に終了した後に表示される文字列または文字列のリストを返します。

これらの文字列は、標準の "collected X items" メッセージの後に表示されます。

Added in version 3.2.

パラメータ:

config (Config) -- pytest 設定オブジェクト。
start_path (pathlib.Path) -- 開始ディレクトリ。
startdir (LEGACY_PATH) -- 開始ディレクトリ（非推奨）。
items (Sequence[Item]) -- 実行される予定の pytest アイテムのリスト。このリストは変更しないでください。

注釈

conftest プラグインで使用する¶

任意の conftest プラグインがこのフックを実装できます。

pytest_report_teststatus(report, config)[ソース]¶

ステータスレポートのために、結果カテゴリ、短い文字、および詳細な単語を返します。

結果カテゴリは、結果をカウントするカテゴリです。例えば "passed"、"skipped"、"error" または空文字列です。

短い文字は、テストの進行中に表示されます。例えば "."、"s"、"E" または空文字列です。

詳細な単語は、詳細モードでテストの進行中に表示されます。例えば "PASSED"、"SKIPPED"、"ERROR" または空文字列です。

pytest はレポートの結果に応じてこれらを暗黙的にスタイル設定する場合があります。明示的なスタイル設定を提供するには、詳細な単語のタプルを返します。例えば "rerun", "R", ("RERUN", {"yellow": True}) のように。

パラメータ:

report (CollectReport | TestReport) -- ステータスを返すレポートオブジェクト。
config (Config) -- pytest 設定オブジェクト。

戻り値:

テストステータス。

戻り値の型:

TestShortLogReport | tuple[str, str, str | tuple[str, Mapping[str, bool]]]

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

conftest プラグインで使用する¶

任意の conftest プラグインがこのフックを実装できます。

pytest_report_to_serializable(config, report)[ソース]¶

レポートオブジェクトをシリアライズして、例えば JSON に変換するなど、ワイヤー越しに送信するのに適したデータ構造にします。

パラメータ:

config (Config) -- pytest 設定オブジェクト。
report (CollectReport | TestReport) -- レポート。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。詳細は、このフックを呼び出すプラグインによって異なる場合があります。

pytest_report_from_serializable(config, data)[ソース]¶

pytest_report_to_serializable で以前にシリアライズされたレポートオブジェクトを復元します。

パラメータ:: config (Config) -- pytest 設定オブジェクト。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。詳細は、このフックを呼び出すプラグインによって異なる場合があります。

pytest_terminal_summary(terminalreporter, exitstatus, config)[ソース]¶

ターミナルサマリーレポートにセクションを追加します。

パラメータ:

terminalreporter (TerminalReporter) -- 内部ターミナルレポーターオブジェクト。
exitstatus (ExitCode) -- OS に報告される終了ステータス。
config (Config) -- pytest 設定オブジェクト。

Added in version 4.2: config パラメータ。

conftest プラグインで使用する¶

任意の conftest プラグインがこのフックを実装できます。

pytest_fixture_setup(fixturedef, request)[ソース]¶

フィクスチャのセットアップ実行を行います。

パラメータ:

fixturedef (FixtureDef[Any]) -- フィクスチャ定義オブジェクト。
request (SubRequest) -- フィクスチャリクエストオブジェクト。

戻り値:

フィクスチャ関数の呼び出しの戻り値。

戻り値の型:

object | None

最初の None でない結果で停止します。詳細は firstresult：最初の None でない結果で停止を参照してください。

注釈

フィクスチャ関数が None を返す場合、このフック関数の他の実装は firstresult：最初の None でない結果で停止オプションの動作に従って呼び出され続けます。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。指定されたフィクスチャに対して、フィクスチャスコープのディレクトリおよびその親ディレクトリにある conftest ファイルのみが参照されます。

pytest_fixture_post_finalizer(fixturedef, request)[ソース]¶

フィクスチャのティアダウン後、キャッシュがクリアされる前に呼び出されます。そのため、フィクスチャ結果 fixturedef.cached_result はまだ利用可能です（None ではありません）。

パラメータ:

fixturedef (FixtureDef[Any]) -- フィクスチャ定義オブジェクト。
request (SubRequest) -- フィクスチャリクエストオブジェクト。

conftest プラグインで使用する¶

pytest_warning_recorded(warning_message, when, nodeid, location)[ソース]¶

内部 pytest 警告プラグインによってキャプチャされた警告を処理します。

パラメータ:

warning_message (warnings.WarningMessage) -- キャプチャされた警告。これは warnings.catch_warnings によって生成されたオブジェクトと同じであり、warnings.showwarning() のパラメータと同じ属性を持ちます。
when (Literal['config', 'collect', 'runtest']) --
警告がキャプチャされた時点を示します。可能な値:
- "config": pytest の設定/初期化段階中。
- "collect": テストコレクション中。
- "runtest": テスト実行中。
nodeid (str) -- アイテムの完全な ID。特定のノードに特有でない警告の場合は空文字列。
location (tuple[str, int, str] | None) -- 利用可能な場合、キャプチャされた警告の実行コンテキスト（ファイル名、行番号、関数）に関する情報を保持します。実行コンテキストがモジュールレベルの場合、function は <module> と評価されます。

Added in version 6.0.

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。警告が特定のノードに特有である場合、そのノードの親ディレクトリにある conftest ファイルのみが参照されます。

テスト実行に関するレポートのための中央フック：

pytest_runtest_logreport(report)[ソース]¶

各セットアップ、コール、およびティアダウン runtest フェーズに対して生成された TestReport を処理します。

runtest プロトコルの説明については pytest_runtest_protocol を参照してください。

conftest プラグインで使用する¶

アサーション関連のフック：

pytest_assertrepr_compare(config, op, left, right)[ソース]¶

失敗したアサーション式の比較に対する説明を返します。

カスタムの説明がない場合は None を返し、それ以外の場合は文字列のリストを返します。文字列は改行で結合されますが、文字列内の改行はエスケープされます。最初の行以外は少しインデントされることに注意してください。最初の行は要約のためのものです。

パラメータ:

config (Config) -- pytest 設定オブジェクト。
op (str) -- 演算子。例："=="、"!="、"not in"。
left (object) -- 左オペランド。
right (object) -- 右オペランド。

conftest プラグインで使用する¶

pytest_assertion_pass(item, lineno, orig, expl)[ソース]¶

アサーションが成功するたびに呼び出されます。

Added in version 5.0.

このフックを使用して、成功したアサーションの後に何らかの処理を行います。元のアサーション情報は orig 文字列にあり、pytest によって内省されたアサーション情報は expl 文字列にあります。

このフックは enable_assertion_pass_hook ini ファイルオプションによって明示的に有効にする必要があります：

[pytest]
enable_assertion_pass_hook=true

このオプションを有効にする際には、プロジェクトディレクトリおよびインタープリタライブラリ内の .pyc をクリーンアップ する必要があります。アサーションは再書き込みが必要です。

パラメータ:

item (Item) -- 現在のテストの pytest アイテムオブジェクト。
lineno (int) -- アサート文の行番号。
orig (str) -- 元のアサーションを含む文字列。
expl (str) -- アサートの説明を含む文字列。

conftest プラグインで使用する¶

デバッグ/インタラクションフック¶

例外に対する特別なレポートやインタラクションに使用できるフックがいくつかあります：

pytest_internalerror(excrepr, excinfo)[ソース]¶

内部エラーに対して呼び出されます。

INTERNALERROR メッセージを直接 sys.stderr に出力するフォールバック処理を抑制するには True を返します。

パラメータ:

excrepr (ExceptionRepr) -- 例外の再現オブジェクト。
excinfo (ExceptionInfo[BaseException]) -- 例外情報。

conftest プラグインで使用する¶

任意の conftest プラグインがこのフックを実装できます。

pytest_keyboard_interrupt(excinfo)[ソース]¶

キーボード割り込みに対して呼び出されます。

パラメータ:: excinfo (ExceptionInfo[KeyboardInterrupt | Exit]) -- 例外情報。

conftest プラグインで使用する¶

任意の conftest プラグインがこのフックを実装できます。

pytest_exception_interact(node, call, report)[ソース]¶

インタラクティブに処理できる可能性のある例外が発生したときに呼び出されます。

コレクション中に呼び出される場合があります（pytest_make_collect_report を参照）。この場合、report は CollectReport です。

アイテムの runtest 中に呼び出される場合があります（pytest_runtest_protocol を参照）。この場合、report は TestReport です。

発生した例外が skip.Exception のような内部例外である場合、このフックは呼び出されません。

パラメータ:

node (Item | Collector) -- アイテムまたはコレクター。
call (CallInfo[Any]) -- 呼び出し情報。例外を含みます。
report (CollectReport | TestReport) -- コレクションまたはテストレポート。

conftest プラグインで使用する¶

任意の conftest ファイルがこのフックを実装できます。指定されたノードに対して、そのノードの親ディレクトリにある conftest ファイルのみが参照されます。

pytest_enter_pdb(config, pdb)[ソース]¶

pdb.set_trace() が呼び出されたときに呼び出されます。

プラグインが Python デバッガーがインタラクティブモードに入る直前に特別なアクションを実行するために使用できます。

パラメータ:

config (Config) -- pytest 設定オブジェクト。
pdb (pdb.Pdb) -- Pdb インスタンス。

conftest プラグインで使用する¶

任意の conftest プラグインがこのフックを実装できます。

pytest_leave_pdb(config, pdb)[ソース]¶

pdb を離れるときに呼び出されます（例：pdb.set_trace() の後に continue で）。

プラグインが Python デバッガーがインタラクティブモードを離れた直後に特別なアクションを実行するために使用できます。

パラメータ:

config (Config) -- pytest 設定オブジェクト。
pdb (pdb.Pdb) -- Pdb インスタンス。

conftest プラグインで使用する¶

任意の conftest プラグインがこのフックを実装できます。

コレクションツリーオブジェクト¶

これらは、コレクションツリーを構成するコレクターおよびアイテムクラス（総称して「ノード」と呼ばれます）です。

ノード¶

class Node[ソース]¶

ベースクラス: ABC

Collector および Item の基本クラス。これらはテストコレクションツリーのコンポーネントです。

Collector はツリーの内部ノードであり、Item はリーフノードです。

fspath: LEGACY_PATH¶: LEGACY_PATH の path 属性のコピー。 Item.reportinfo など、まだ pathlib.Path に移行されていないメソッドの使用を意図しています。将来のリリースで非推奨となる予定です。代わりに path を使用してください。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

keywords: MutableMapping[str, Any]¶: すべてのスコープから収集されたキーワード/マーカー。

own_markers: list[Mark]¶: このノードに属するマーカーオブジェクト。

extra_keyword_matches: set[str]¶: マッチングに使用する追加のキーワードを追加できます。

stash: Stash¶: プラグインがノードに関する情報を独自に使用するために保存できる場所。

classmethod from_parent(parent, **kw)[ソース]¶

ノードの公開コンストラクター。

この間接参照は、ノードコンストラクターから脆弱なロジックを削除できるようにするために導入されました。

サブクラスは、コンストラクションをオーバーライドする際に super().from_parent(...) を使用できます。

パラメータ:: parent (Node) -- このノードの親ノード。

property ihook: HookRelay¶: pytest フックを呼び出すために使用される fspath に敏感なフックプロキシ。

warn(warning)[ソース]¶

このノードに対して警告を発行します。

警告はテストセッションの後に表示されます。明示的に抑制されない限り。

パラメータ:: warning (Warning) -- 発行する警告インスタンス。
例外:: ValueError -- warning インスタンスが Warning のサブクラスでない場合。

使用例：

node.warn(PytestWarning("some message"))
node.warn(UserWarning("some message"))

バージョン 6.2 で変更: Warning の任意のサブクラスが受け入れられるようになりました。以前は PytestWarning のサブクラスのみでした。

property nodeid: str¶: コレクションツリーアドレスを示す :: で区切られた文字列。

for ... in iter_parents()[ソース]¶

コレクションツリーのルートまで、自己を含むすべての親コレクターを反復処理します。

Added in version 8.1.

listchain()[ソース]¶

コレクションツリーのルートから自己を含むすべての親コレクターのリストを返します。

add_marker(marker, append=True)[ソース]¶

マーカーオブジェクトをノードに動的に追加します。

パラメータ:

marker (str | MarkDecorator) -- マーカー。
append (bool) -- マーカーを追加するか、先頭に追加するか。

iter_markers(name=None)[ソース]¶

ノードのすべてのマーカーを反復処理します。

パラメータ:: name (str | None) -- 指定された場合、name 属性で結果をフィルタリングします。
戻り値:: ノードのマーカーのイテレータ。
戻り値の型:: Iterator[Mark]

for ... in iter_markers_with_node(name=None)[ソース]¶

ノードのすべてのマーカーを反復処理します。

パラメータ:: name (str | None) -- 指定された場合、name 属性で結果をフィルタリングします。
戻り値:: (node, mark) タプルのイテレータ。
戻り値の型:: Iterator[tuple[Node, Mark]]

get_closest_marker(name: str) → Mark | None[ソース]¶

get_closest_marker(name: str, default: Mark) → Mark

名前に一致する最初のマーカーを返します。最も近いレベル（例えば関数）から遠いレベル（例えばモジュールレベル）まで。

パラメータ:

default -- マーカーが見つからなかった場合のフォールバック戻り値。
name -- フィルタリングする名前。

listextrakeywords()[ソース]¶

自己および任意の親にあるすべての追加キーワードのセットを返します。

addfinalizer(fin)[ソース]¶

このノードが終了するときに引数なしで呼び出される関数を登録します。

このメソッドは、このノードがセットアップチェーンでアクティブな場合にのみ呼び出すことができます。例えば self.setup() 中に。

getparent(cls)[ソース]¶

指定されたクラスのインスタンスである最も近い親ノード（自己を含む）を取得します。

パラメータ:: cls (type[_NodeType]) -- 検索するノードクラス。
戻り値:: 見つかった場合のノード。
戻り値の型:: _NodeType | None

repr_failure(excinfo, style=None)[ソース]¶

コレクションまたはテストの失敗の表現を返します。

参考

非 Python テストの操作

パラメータ:: excinfo (ExceptionInfo[BaseException]) -- 失敗の例外情報。

コレクター¶

class Collector[ソース]¶

ベースクラス: Node, ABC

すべてのコレクターの基本クラス。

コレクターは collect() を通じて子を作成し、コレクションツリーを反復的に構築します。

exception CollectError[ソース]¶

ベースクラス: Exception

コレクション中のエラー。カスタムメッセージを含みます。

abstractmethod collect()[ソース]¶

このコレクターの子（アイテムおよびコレクター）を収集します。

repr_failure(excinfo)[ソース]¶

コレクションの失敗の表現を返します。

パラメータ:: excinfo (ExceptionInfo[BaseException]) -- 失敗の例外情報。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

アイテム¶

class Item[ソース]¶

ベースクラス: Node, ABC

すべてのテスト呼び出しアイテムの基本クラス。

単一の関数に対して複数のテスト呼び出しアイテムが存在する場合があることに注意してください。

user_properties: list[tuple[str, object]]¶: このテストのユーザー定義プロパティを保持する (name, value) タプルのリスト。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

abstractmethod runtest()[ソース]¶

このアイテムのテストケースを実行します。

サブクラスによって実装される必要があります。

参考

非 Python テストの操作

add_report_section(when, key, content)[ソース]¶

新しいレポートセクションを追加します。標準出力および標準エラーキャプチャ出力を追加するために内部で行われることと同様です：

item.add_report_section("call", "stdout", "report section contents")

パラメータ:

when (str) -- 可能なキャプチャ状態のいずれか。 "setup"、"call"、"teardown"。
key (str) -- セクションの名前。自由にカスタマイズできます。 Pytest は内部的に "stdout" および "stderr" を使用します。
content (str) -- 文字列としての完全な内容。

reportinfo()[ソース]¶

テストレポートのためにこのアイテムの場所情報を取得します。

3 つの要素を持つタプルを返します：

テストのパス（デフォルトは self.path）
テストの 0 ベースの行番号（デフォルトは None）
表示されるテストの名前（デフォルトは ""）

参考

非 Python テストの操作

property location: tuple[str, int | None, str]¶: このアイテムの (relfspath, lineno, testname) のタプルを返します。ここで relfspath は config.rootpath に対するファイルパスであり、lineno は 0 ベースの行番号です。

ファイル¶

class File[ソース]¶

ベースクラス: FSCollector, ABC

ファイルからテストを収集するための基本クラス。

非 Python テストの操作。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

FSCollector¶

class FSCollector[ソース]¶

ベースクラス: Collector, ABC

ファイルシステムコレクターの基本クラス。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

classmethod from_parent(parent, *, fspath=None, path=None, **kw)[ソース]¶

公開コンストラクター。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

セッション¶

final class Session[ソース]¶

ベースクラス: Collector

コレクションツリーのルート。

Session は pytest に引数として渡された初期パスを収集します。

exception Interrupted¶

ベースクラス: KeyboardInterrupt

テスト実行が中断されたことを示します。

exception Failed¶

ベースクラス: Exception

失敗したテスト実行として停止を示します。

property startpath: Path¶: pytest が呼び出されたパス。

Added in version 7.0.0.

isinitpath(path, *, with_parents=False)[ソース]¶

パスは初期パスですか？

初期パスは、コマンドラインで pytest に明示的に渡されたパスです。

パラメータ:: with_parents (bool) -- 設定されている場合、パスが初期パスの親である場合も True を返します。

バージョン 8.0 で変更: with_parents パラメータが追加されました。

perform_collect(args: Sequence[str] | None = None, genitems: Literal[True] = True) → Sequence[Item][ソース]¶

perform_collect(args: Sequence[str] | None = None, genitems: bool = True) → Sequence[Item | Collector]

このセッションのコレクションフェーズを実行します。

これはデフォルトの pytest_collection フック実装によって呼び出されます。詳細については、このフックのドキュメントを参照してください。テスト目的で、新しい Session に対して直接呼び出すこともできます。

この関数は通常、セッションから収集されたコレクターを再帰的に展開してそのアイテムにし、アイテムのみを返します。テスト目的で、genitems=False を渡すことでこれを抑制できます。この場合、戻り値にはこれらのコレクターが未展開のまま含まれ、session.items は空です。

for ... in collect()[ソース]¶

このコレクターの子（アイテムおよびコレクター）を収集します。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

パッケージ¶

class Package[ソース]¶

ベースクラス: Directory

Python パッケージ内のファイルおよびディレクトリのコレクター -- __init__.py ファイルを持つディレクトリ。

注釈

Directories without an __init__.py file are instead collected by Dir by default. Both are Directory collectors.

バージョン 8.0 で変更: 現在は Directory から継承しています。

for ... in collect()[ソース]¶

このコレクターの子（アイテムおよびコレクター）を収集します。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

モジュール¶

class Module[ソース]¶

ベースクラス: File, PyCollector

Python モジュール内のテストクラスおよび関数のコレクター。

collect()[ソース]¶

このコレクターの子（アイテムおよびコレクター）を収集します。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

クラス¶

class Class[ソース]¶

ベースクラス: PyCollector

Python クラス内のテストメソッド（およびネストされたクラス）のコレクター。

classmethod from_parent(parent, *, name, obj=None, **kw)[ソース]¶

公開コンストラクター。

collect()[ソース]¶

このコレクターの子（アイテムおよびコレクター）を収集します。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

関数¶

class Function[ソース]¶

ベースクラス: PyobjMixin, Item

Python テスト関数のセットアップおよび実行を担当するアイテム。

パラメータ:

name -- パラメータ化によって追加された装飾などを含む完全な関数名（my_func[my_param]）。
parent -- 親ノード。
config -- pytest 設定オブジェクト。
callspec -- 指定された場合、この関数はパラメータ化されており、callspec にはパラメータ化に関するメタ情報が含まれます。
callobj -- 指定された場合、関数が呼び出されたときに呼び出されるオブジェクト。それ以外の場合、callobj は parent から originalname を使用して取得されます。
keywords -- 関数オブジェクトにバインドされたキーワード。 "-k" マッチングのため。
session -- pytest セッションオブジェクト。
fixtureinfo -- このフィクスチャノードで既に解決されたフィクスチャ情報。
originalname -- 基礎となる関数オブジェクトにアクセスするために使用する属性名。デフォルトは name です。名前が元の名前と異なる場合、例えばパラメータ化によって追加された装飾が含まれる場合（my_func[my_param]）、これを設定します。

originalname¶: 装飾なしの元の関数名（例えばパラメータ化は関数名に "[...]" サフィックスを追加します）。 parent から基礎となる関数オブジェクトにアクセスするために使用されます（callobj が明示的に指定されていない場合）。

Added in version 3.0.

classmethod from_parent(parent, **kw)[ソース]¶

公開コンストラクター。

property function¶: 基礎となる Python の 'function' オブジェクト。

property instance¶

関数がバインドされている Python インスタンスオブジェクト。

テストメソッドでない場合、None を返します。例えば、スタンドアロンのテスト関数、クラス、またはモジュールの場合。

runtest()[ソース]¶

基礎となるテスト関数を実行します。

repr_failure(excinfo)[ソース]¶

コレクションまたはテストの失敗の表現を返します。

参考

非 Python テストの操作

パラメータ:: excinfo (ExceptionInfo[BaseException]) -- 失敗の例外情報。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

関数定義¶

class FunctionDefinition[ソース]¶

ベースクラス: Function

このクラスは、実際の関数定義ノードを持つように進化し、metafunc を取り除くまでの暫定的な解決策です。

runtest()[ソース]¶

基礎となるテスト関数を実行します。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

setup()¶

基礎となるテスト関数を実行します。

オブジェクト¶

fixtures または hooks からアクセス可能なオブジェクト、または pytest からインポート可能なオブジェクト。

CallInfo¶

final class CallInfo[ソース]¶

関数呼び出しの結果/例外情報。

excinfo: ExceptionInfo[BaseException] | None¶: 呼び出し時にキャプチャされた例外（発生した場合）。

start: float¶: 呼び出しが開始されたシステム時刻（エポックからの秒数）。

stop: float¶: 呼び出しが終了したシステム時刻（エポックからの秒数）。

duration: float¶: 呼び出しの持続時間（秒）。

when: Literal['collect', 'setup', 'call', 'teardown']¶: 呼び出しのコンテキスト："collect"、"setup"、"call"、または "teardown"。

property result: TResult¶

呼び出しの戻り値（例外が発生しなかった場合）。

excinfo が None の場合にのみアクセスできます。

classmethod from_call(func, when, reraise=None)[ソース]¶

関数を呼び出し、結果を CallInfo にラップします。

パラメータ:

func (Callable[[], _pytest.runner.TResult]) -- 呼び出す関数。引数なしで呼び出されます。
when (Literal['collect', 'setup', 'call', 'teardown']) -- 関数が呼び出されるフェーズ。
reraise (type[BaseException] | tuple[type[BaseException], ...] | None) -- 関数によって発生した場合に CallInfo にラップされずに伝播する例外または例外群。

CollectReport¶

final class CollectReport[ソース]¶

ベースクラス: BaseReport

コレクションレポートオブジェクト。

レポートには任意の追加属性を含めることができます。

nodeid: str¶: 正規化されたコレクション nodeid。

outcome: Literal['passed', 'failed', 'skipped']¶: テストの結果。常に "passed"、"failed"、"skipped" のいずれか。

longrepr: None | ExceptionInfo[BaseException] | tuple[str, int, str] | str | TerminalRepr¶: None または失敗の表現。

result¶: 収集されたアイテムおよびコレクションノード。

sections: list[tuple[str, str]]¶: テストレポートの追加情報を含む (heading, content) の文字列タプル。 pytest は stdout、stderr からキャプチャされたテキストやインターセプトされたログイベントを追加するために使用します。他のプラグインがレポートに任意の情報を追加するために使用することもできます。

property caplog: str¶: ログキャプチャが有効な場合、キャプチャされたログ行を返します。

Added in version 3.5.

property capstderr: str¶: キャプチャが有効な場合、stderr からキャプチャされたテキストを返します。

Added in version 3.0.

property capstdout: str¶: キャプチャが有効な場合、stdout からキャプチャされたテキストを返します。

Added in version 3.0.

property count_towards_summary: bool¶: 実験的 このレポートがテストセッションの最後に表示される合計（"1 passed, 1 failure" など）にカウントされるかどうか。

注釈

この関数は 実験的 と見なされているため、パッチリリースでも変更される可能性があることに注意してください。

property failed: bool¶: 結果が失敗したかどうか。

property fspath: str¶: 報告されたノードのパス部分（文字列として）。

property head_line: str | None¶

実験的 このレポートの longrepr 出力に表示されるヘッドライン。通常は失敗時のトレースバック表現中に表示されます：

________ Test.foo ________

上記の例では、ヘッドラインは "Test.foo" です。

注釈

この関数は 実験的 と見なされているため、パッチリリースでも変更される可能性があることに注意してください。

property longreprtext: str¶: longrepr の完全な文字列表現を返す読み取り専用プロパティ。

Added in version 3.0.

property passed: bool¶: 結果が成功したかどうか。

property skipped: bool¶: 結果がスキップされたかどうか。

Config¶

final class Config[ソース]¶

設定値、プラグインマネージャー、およびプラグインフックへのアクセス。

パラメータ:

pluginmanager (PytestPluginManager) -- pytest プラグインマネージャー。
invocation_params (InvocationParams) -- pytest.main() 呼び出しに関するパラメータを含むオブジェクト。

final class InvocationParams(*, args, plugins, dir)[ソース]¶

pytest.main() 呼び出し中に渡されたパラメータを保持します。

オブジェクトの属性は読み取り専用です。

Added in version 5.1.

注釈

環境変数 PYTEST_ADDOPTS および addopts ini オプションは pytest によって処理され、args 属性には含まれないことに注意してください。

InvocationParams にアクセスするプラグインはそれを認識している必要があります。

args: tuple[str, ...]¶: pytest.main() に渡されたコマンドライン引数。

plugins: Sequence[str | object] | None¶: 追加のプラグイン。 None の場合があります。

dir: Path¶: pytest.main() が呼び出されたディレクトリ。 :type: pathlib.Path

class ArgsSource(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[ソース]¶

テスト引数のソースを示します。

Added in version 7.2.

ARGS = 1¶: コマンドライン引数。

INVOCATION_DIR = 2¶: 呼び出しディレクトリ。

TESTPATHS = 3¶: 'testpaths' 設定値。

option¶

属性としてコマンドラインオプションにアクセスします。

Type:: argparse.Namespace

invocation_params¶

pytest が呼び出されたパラメータ。

Type:: InvocationParams

pluginmanager¶

プラグインマネージャーはプラグインの登録とフックの呼び出しを処理します。

Type:: PytestPluginManager

stash¶

プラグインが独自に使用するために設定情報を保存できる場所。

Type:: Stash

property rootpath: Path¶

rootdir へのパス。

Type:: pathlib.Path

Added in version 6.1.

property inipath: Path | None¶: configfile へのパス。

Added in version 6.1.

add_cleanup(func)[ソース]¶

設定オブジェクトが使用されなくなったときに呼び出される関数を追加します（通常は pytest_unconfigure と一致します）。

classmethod fromdictargs(option_dict, args)[ソース]¶

サブプロセスで使用可能なコンストラクター。

issue_config_time_warning(warning, stacklevel)[ソース]¶

"configure" ステージ中に警告を発行および処理します。

pytest_configure 中は、catch_warnings_for_item 関数を使用して警告をキャプチャすることはできません。 pytest_configure の周りにフックラッパーを配置することはできないためです。

この関数は主に、pytest_configure (または同様のステージ) 中に警告を発行する必要があるプラグインを対象としています。

パラメータ:

warning (Warning) -- 警告インスタンス。
stacklevel (int) -- warnings.warn に転送される stacklevel。

addinivalue_line(name, line)[ソース]¶

ini ファイルオプションに行を追加します。オプションは宣言されている必要がありますが、まだ設定されていない場合は、その行が値の最初の行になります。

getini(name)[ソース]¶

ini ファイルから設定値を返します。

If a configuration value is not defined in an ini file, then the default value provided while registering the configuration through parser.addini will be returned. Please note that you can even provide None as a valid default value.

parser.addini を使用して設定を登録する際に default 値が提供されていない場合、parser.addini に渡された type パラメータに基づいてデフォルト値が返されます。 type に基づくデフォルト値は次のとおりです: paths、pathlist、args、および linelist : 空のリスト [] bool : False string : 空の文字列 ""

parser.addini を使用して設定を登録する際に default も type パラメータも渡されない場合、設定は文字列として扱われ、デフォルトの空の文字列 '' が返されます。

指定された名前が以前の parser.addini 呼び出し（通常はプラグインから）を通じて登録されていない場合、ValueError が発生します。

getoption(name, default=<NOTSET>, skip=False)[ソース]¶

コマンドラインオプションの値を返します。

パラメータ:

name (str) -- オプションの名前。リテラル --OPT オプションを指定することもできます。
default -- その名前のオプションが pytest_addoption を通じて宣言されていない場合のフォールバック値。このパラメータは、オプションが宣言されている場合、オプションの値が None であっても無視されます。
skip (bool) -- True の場合、オプションが宣言されていないか、値が None の場合に pytest.skip() を発生させます。 True であっても、デフォルトが指定されている場合はスキップの代わりにその値が返されます。

getvalue(name, path=None)[ソース]¶

非推奨、代わりに getoption() を使用してください。

getvalueorskip(name, path=None)[ソース]¶

非推奨、代わりに getoption(skip=True) を使用してください。

VERBOSITY_ASSERTIONS: Final = 'assertions'¶: 失敗したアサーションの詳細度タイプ（verbosity_assertions を参照）。

VERBOSITY_TEST_CASES: Final = 'test_cases'¶: テストケース実行の詳細度タイプ（verbosity_test_cases を参照）。

get_verbosity(verbosity_type=None)[ソース]¶

詳細度タイプの詳細度レベルを取得します。

パラメータ:: verbosity_type (str | None) -- 詳細度レベルを取得するための詳細度タイプ。指定されたタイプに対してレベルが設定されている場合、その値が返されます。指定されたタイプが既知の詳細度タイプでない場合、グローバル詳細度レベルが返されます。指定されたタイプが None（デフォルト）の場合、グローバル詳細度レベルが返されます。

詳細度タイプのレベルを設定するには、設定ファイルに設定名と詳細度レベルの数値を設定する必要があります。特別な値 "auto" を使用して、グローバル詳細度レベルを明示的に使用することができます。

例:

# content of pytest.ini
[pytest]
verbosity_assertions = 2

pytest -v

print(config.get_verbosity())  # 1
print(config.get_verbosity(Config.VERBOSITY_ASSERTIONS))  # 2

Dir¶

final class Dir[ソース]¶

ファイルシステムディレクトリ内のファイルのコレクター。

Added in version 8.0.

注釈

Python ディレクトリに __init__.py ファイルがある場合、代わりにデフォルトで Package によって収集されます。どちらも Directory コレクターです。

classmethod from_parent(parent, *, path)[ソース]¶

公開コンストラクター。

パラメータ:

parent (nodes.Collector) -- この Dir の親コレクター。
path (pathlib.Path) -- ディレクトリのパス。

for ... in collect()[ソース]¶

このコレクターの子（アイテムおよびコレクター）を収集します。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

ディレクトリ¶

class Directory[ソース]¶

ディレクトリからファイルを収集するための基本クラス。

基本的なディレクトリコレクターは次のことを行います: ディレクトリ内のファイルおよびサブディレクトリを調べ、pytest_collect_directory および pytest_collect_file フックを呼び出してそれらのコレクターを作成します。ただし、pytest_ignore_collect を使用して無視されていないことを確認します。

デフォルトのディレクトリコレクターは Dir および Package です。

Added in version 8.0.

カスタムディレクトリコレクタの使用。

name: str¶: 親ノードのスコープ内で一意の名前。

parent¶: 親コレクターノード。

config: Config¶: pytest 設定オブジェクト。

session: Session¶: このノードが属する pytest セッション。

path: pathlib.Path¶: このノードが収集されたファイルシステムパス（None の場合があります）。

ExceptionInfo¶

final class ExceptionInfo[ソース]¶

sys.exc_info() オブジェクトをラップし、トレースバックのナビゲートを支援します。

classmethod from_exception(exception, exprinfo=None)[ソース]¶

既存の例外に対する ExceptionInfo を返します。

例外は非 None の __traceback__ 属性を持っている必要があります。そうでない場合、この関数はアサーションエラーで失敗します。これは、例外が発生したか、with_traceback() メソッドでトレースバックが追加されたことを意味します。

パラメータ:: exprinfo (str | None) -- A text string helping to determine if we should strip AssertionError from the output. Defaults to the exception message/__str__().

Added in version 7.4.

classmethod from_exc_info(exc_info, exprinfo=None)[ソース]¶

Like from_exception(), but using old-style exc_info tuple.

classmethod from_current(exprinfo=None)[ソース]¶

現在のトレースバックに一致する ExceptionInfo を返します。

警告

実験的 API

パラメータ:: exprinfo (str | None) -- A text string helping to determine if we should strip AssertionError from the output. Defaults to the exception message/__str__().

classmethod for_later()[ソース]¶

未入力の ExceptionInfo を返します。

fill_unfilled(exc_info)[ソース]¶

for_later() で作成された未入力の ExceptionInfo を入力します。

property type: type[E]¶: 例外クラス。

property value: E¶: 例外値。

property tb: TracebackType¶: 例外の生のトレースバック。

property typename: str¶: 例外の型名。

property traceback: Traceback¶: トレースバック。

exconly(tryshort=False)[ソース]¶

例外を文字列として返します。

'tryshort' が True に解決され、例外が AssertionError の場合、例外表現の実際の例外部分のみが返されます（したがって、'AssertionError: ' は先頭から削除されます）。

errisinstance(exc)[ソース]¶

例外が exc のインスタンスである場合は True を返します。

代わりに isinstance(excinfo.value, exc) を使用することを検討してください。

getrepr(showlocals=False, style='long', abspath=False, tbfilter=True, funcargs=False, truncate_locals=True, truncate_args=True, chain=True)[ソース]¶

この例外情報の str() 可能な表現を返します。

パラメータ:

showlocals (bool) -- トレースバックエントリごとにローカルを表示します。 style=="native" の場合は無視されます。
style (str) -- long|short|line|no|native|value トレースバックスタイル。
abspath (bool) -- パスを絶対パスに変更するか、そのままにするか。
tbfilter (bool | Callable[[ExceptionInfo[BaseException]], Traceback]) -- トレースバックエントリのフィルタ。 * false の場合、エントリを非表示にしません。 * true の場合、内部エントリおよびローカル変数 __tracebackhide__ = True を含むエントリを非表示にします。 * callable の場合、フィルタリングを callable に委任します。 style が "native" の場合は無視されます。
funcargs (bool) -- トレースバックエントリごとにフィクスチャ（レガシー目的の "funcargs"）を表示します。
truncate_locals (bool) -- showlocals==True の場合、ローカルが安全に文字列として表現できることを確認します。
truncate_args (bool) -- showargs==True の場合、引数が安全に文字列として表現できることを確認します。
chain (bool) -- Python 3 で連鎖した例外を表示するかどうか。

バージョン 3.9 で変更: chain パラメータが追加されました。

match(regexp)[ソース]¶

正規表現 regexp が例外の文字列表現に一致するかどうかを re.search() を使用して確認します。

一致する場合は True が返され、一致しない場合は AssertionError が発生します。

group_contains(expected_exception, *, match=None, depth=None)[ソース]¶

キャプチャされた例外グループが一致する例外を含むかどうかを確認します。

パラメータ:

expected_exception (Type[BaseException] | Tuple[Type[BaseException]]) -- 予期される例外タイプ、または複数の可能な例外タイプのいずれかが予期される場合のタプル。
match (str | Pattern[str] | None) -- 指定されている場合、正規表現を含む文字列、または正規表現オブジェクト。例外の文字列表現およびその PEP-678 <https://peps.python.org/pep-0678/> __notes__ に対して re.search() を使用してテストされます。特殊文字を含む可能性のあるリテラル文字列に一致させるには、パターンを最初に re.escape() でエスケープできます。
depth (Optional[int]) -- None の場合、一致する例外を任意のネスティング深度で検索します。 >= 1 の場合、指定された深度で例外が一致する場合にのみ一致します（深度 = 1 は最上位の例外グループに含まれる例外）。

Added in version 8.0.

ExitCode¶

final class ExitCode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[ソース]¶

pytest によってエンコードされた有効な終了コード。

現在、ユーザーおよびプラグインは他の終了コードも提供する場合があります。

Added in version 5.0.

OK = 0¶: テストが成功しました。

TESTS_FAILED = 1¶: テストが失敗しました。

INTERRUPTED = 2¶: pytest が中断されました。

INTERNAL_ERROR = 3¶: 内部エラーが発生しました。

USAGE_ERROR = 4¶: pytest が誤用されました。

NO_TESTS_COLLECTED = 5¶: pytest がテストを見つけられませんでした。

FixtureDef¶

final class FixtureDef[ソース]¶

ベースクラス: Generic[FixtureValue]

フィクスチャ定義のコンテナ。

注：現時点では、明示的に文書化されたフィールドおよびメソッドのみが公開安定 API と見なされます。

property scope: Literal['session', 'package', 'module', 'class', 'function']¶: スコープ文字列。 "function"、"class"、"module"、"package"、"session" のいずれか。

execute(request)[ソース]¶

キャッシュされていない場合、このフィクスチャの値を返し、実行します。

MarkDecorator¶

class MarkDecorator[ソース]¶

テスト関数およびクラスにマークを適用するためのデコレーター。

MarkDecorators は pytest.mark で作成されます：

mark1 = pytest.mark.NAME  # Simple MarkDecorator
mark2 = pytest.mark.NAME(name1=value)  # Parametrized MarkDecorator

その後、テスト関数にデコレーターとして適用できます：

@mark2
def test_function():
    pass

MarkDecorator が呼び出されると、次のことが行われます：

単一のクラスを唯一の位置引数として追加のキーワード引数なしで呼び出された場合、マークをクラスにアタッチし、そのクラス内で見つかったすべてのテストケースに自動的に適用されるようにします。
単一の関数を唯一の位置引数として追加のキーワード引数なしで呼び出された場合、マークを関数にアタッチし、MarkDecorator に内部的に格納されているすべての引数を含みます。
他のいずれかの場合に呼び出された場合、元の MarkDecorator の内容をこの呼び出しに渡された引数で更新した新しい MarkDecorator インスタンスを返します。

注：上記のルールにより、MarkDecorator が追加のキーワード引数や位置引数なしで唯一の位置引数として単一の関数またはクラス参照のみを格納することはできません。これを回避するには、with_args() を使用できます。

property name: str¶: mark.name のエイリアス。

property args: tuple[Any, ...]¶: mark.args のエイリアス。

property kwargs: Mapping[str, Any]¶: mark.kwargs のエイリアス。

with_args(*args, **kwargs)[ソース]¶

追加の引数を追加して MarkDecorator を返します。

MarkDecorator を呼び出すのとは異なり、with_args() は唯一の引数が callable/クラスであっても使用できます。

MarkGenerator¶

final class MarkGenerator[ソース]¶

MarkDecorator オブジェクトのファクトリ - pytest.mark シングルトンインスタンスとして公開されます。

例:

import pytest


@pytest.mark.slowtest
def test_function():
    pass

'slowtest' Mark を test_function に適用します。

Mark¶

final class Mark[ソース]¶

pytest マーク。

name: str¶: マークの名前。

args: tuple[Any, ...]¶: マークデコレーターの位置引数。

kwargs: Mapping[str, Any]¶: マークデコレーターのキーワード引数。

combined_with(other)[ソース]¶

この Mark と別の Mark の組み合わせである新しい Mark を返します。

引数を追加し、キーワード引数をマージすることで組み合わせます。

パラメータ:: other (Mark) -- 組み合わせるマーク。
戻り値の型:: Mark

Metafunc¶

final class Metafunc[ソース]¶

pytest_generate_tests フックに渡されるオブジェクト。

テスト関数を検査し、テスト関数が定義されているクラスまたはモジュールで指定されたテスト構成または値に従ってテストを生成するのに役立ちます。

definition¶: 基礎となる _pytest.python.FunctionDefinition へのアクセス。

config¶: テストセッションの pytest.Config オブジェクトへのアクセス。

module¶: テスト関数が定義されているモジュールオブジェクト。

function¶: 基礎となる Python テスト関数。

fixturenames¶: テスト関数が必要とするフィクスチャ名のセット。

cls¶: テスト関数が定義されているクラスオブジェクト、または None。

parametrize(argnames, argvalues, indirect=False, ids=None, scope=None, *, _param_mark=None)[ソース]¶

指定された argnames に対して argvalues のリストを使用して基になるテスト関数に新しい呼び出しを追加します。パラメータ化は収集フェーズ中に実行されます。高価なリソースをセットアップする必要がある場合は、テストのセットアップ時ではなく、それを行うために indirect を設定することについて調べてください。

テスト関数ごとに複数回呼び出すことができます (ただし、異なる引数名のみ) 、この場合、各呼び出しはすべての前のパラメータ化をパラメータ化します。例：

unparametrized:         t
parametrize ["x", "y"]: t[x], t[y]
parametrize [1, 2]:     t[x-1], t[x-2], t[y-1], t[y-2]

パラメータ:

argnames (str | Sequence[str]) -- 1 つ以上の引数名を示すカンマ区切りの文字列、または引数文字列のリスト/タプル。
argvalues (Iterable[_pytest.mark.structures.ParameterSet | Sequence[object] | object]) -- argvalues のリストは、テストが異なる引数値で呼び出される回数を決定します。 1 つの argname のみが指定された場合、argvalues は値のリストです。 N 個の argnames が指定された場合、argvalues は N-タプルのリストでなければなりません。各タプル要素は、それぞれの argname の値を指定します。
indirect (bool | Sequence[str]) -- 引数名のリスト (argnames の部分集合) またはブール値。 True の場合、リストには argnames のすべての名前が含まれます。このリスト内の argname に対応する各 argvalue は、それぞれの argname フィクスチャ関数に request.param として渡されるため、テストのセットアップフェーズではなく収集時により高価なセットアップを行うことができます。
ids (Iterable[object | None] | Callable[[Any], object | None] | None) -- argvalues の id のシーケンス (またはジェネレータ) または各 argvalue の id の一部を返すための呼び出し可能オブジェクト。シーケンス (および itertools.count() のようなジェネレータ) の場合、返される id は string、int、float、bool、または None の型である必要があります。これらは argvalues の対応するインデックスにマップされます。 None は自動生成された id を使用することを意味します。呼び出し可能オブジェクトの場合、argvalues の各エントリに対して呼び出され、返された値は、セット全体の自動生成された id の一部として使用されます (部分はダッシュ ("-") で結合されます) 。これは、特定のアイテムに対してより具体的な id を提供するために便利です。たとえば、日付。 None を返すと、自動生成された id が使用されます。 id が提供されていない場合、argvalues から自動的に生成されます。
scope (Literal['session', 'package', 'module', 'class', 'function'] | None) -- 指定されている場合、パラメータのスコープを示します。スコープは、パラメータインスタンスごとにテストをグループ化するために使用されます。これは、フィクスチャ関数で定義されたスコープを上書きし、テストコンテキストや構成を使用して動的スコープを設定することができます。

パーサー¶

final class Parser[ソース]¶

コマンドライン引数および ini ファイル値のパーサー。

変数:: extra_info -- コマンドライン引数の処理中にエラーが発生した場合に表示する汎用パラメータ -> 値の辞書。

getgroup(name, description='', after=None)[ソース]¶

名前付きオプショングループを取得（または作成）します。

パラメータ:

name (str) -- オプショングループの名前。
description (str) -- --help 出力のための長い説明。
after (str | None) -- --help 出力の順序付けに使用される別のグループの名前。

戻り値:

オプショングループ。

戻り値の型:

OptionGroup

返されるグループオブジェクトには、parser.addoption と同じシグネチャを持つ addoption メソッドがありますが、pytest --help の出力でそれぞれのグループに表示されます。

addoption(*opts, **attrs)[ソース]¶

コマンドラインオプションを登録します。

パラメータ:

opts (str) -- オプション名。短いオプションまたは長いオプションが使用できます。
attrs (Any) -- argparse ライブラリの add_argument() 関数が受け入れるのと同じ属性。

コマンドライン解析後、オプションは config.option.NAME を介して pytest 設定オブジェクトで利用可能です。ここで NAME は通常、dest 属性を渡すことで設定されます。例えば addoption("--long", dest="NAME", ...)。

parse_known_args(args, namespace=None)[ソース]¶

既知の引数をこの時点で解析します。

戻り値:: argparse 名前空間オブジェクト。
戻り値の型:: Namespace

parse_known_and_unknown_args(args, namespace=None)[ソース]¶

既知の引数をこの時点で解析し、残りの未知の引数も返します。

戻り値:: 既知の引数の argparse 名前空間オブジェクトと、未知の引数のリストを含むタプル。
戻り値の型:: tuple[Namespace, list[str]]

addini(name, help, type=None, default=<notset>)[ソース]¶

ini ファイルオプションを登録します。

パラメータ:

name (str) -- ini 変数の名前。
type (Literal['string', 'paths', 'pathlist', 'args', 'linelist', 'bool'] | None) -- 変数のタイプ。次のいずれかです：* string：文字列* bool：ブール値* args：シェルのように区切られた文字列のリスト* linelist：改行で区切られた文字列のリスト* paths：シェルのように区切られた pathlib.Path のリスト* pathlist：シェルのように区切られた py.path のリスト``paths`` および pathlist タイプの場合、ini ファイルに対して相対的に考慮されます。 ini ファイルが定義されていない場合、現在の作業ディレクトリに対して相対的に考慮されます（例えば --override-ini を使用する場合）。 .. versionadded:: 7.0``paths`` 変数タイプ。 .. versionadded:: 8.1ini ファイルがない場合に paths および pathlist を解決するために現在の作業ディレクトリを使用します。 None または渡されない場合、デフォルトは string です。
default (Any) -- ini ファイルオプションが存在しないがクエリされた場合のデフォルト値。

ini 変数の値は config.getini(name) を呼び出すことで取得できます。

OptionGroup¶

class OptionGroup[ソース]¶

独自のセクションに表示されるオプショングループ。

addoption(*opts, **attrs)[ソース]¶

このグループにオプションを追加します。

長いオプションの短縮版が指定されている場合、ヘルプには表示されません。 addoption('--twowords', '--two-words') はヘルプに --two-words のみを表示しますが、--twowords も受け入れられ、自動的な宛先は args.twowords になります。

パラメータ:

opts (str) -- オプション名。短いオプションまたは長いオプションが使用できます。
attrs (Any) -- argparse ライブラリの add_argument() 関数が受け入れるのと同じ属性。

PytestPluginManager¶

final class PytestPluginManager[ソース]¶

ベースクラス: PluginManager

pluggy.PluginManager で、pytest 固有の追加機能があります：

コマンドライン、PYTEST_PLUGINS 環境変数、および読み込まれるプラグインに見つかる pytest_plugins グローバル変数からプラグインを読み込みます。
起動時の conftest.py の読み込み。

register(plugin, name=None)[ソース]¶

プラグインを登録し、その名前を返します。

パラメータ:: name (str | None) -- プラグインを登録する名前。指定されていない場合、get_canonical_name() を使用して名前が生成されます。
戻り値:: プラグイン名。名前が登録をブロックされている場合、None を返します。
戻り値の型:: str | None

プラグインが既に登録されている場合、ValueError を発生させます。

getplugin(name)[ソース]¶

hasplugin(name)[ソース]¶

指定された名前のプラグインが登録されているかどうかを返します。

import_plugin(modname, consider_entry_points=False)[ソース]¶

modname でプラグインをインポートします。

consider_entry_points が True の場合、エントリーポイント名もプラグインを見つけるために考慮されます。

add_hookcall_monitoring(before, after)¶

すべてのフックに対して前後のトレース関数を追加します。

呼び出されると、追加されたトレーサーを削除する元に戻す関数を返します。

before(hook_name, hook_impls, kwargs) はすべてのフック呼び出しの前に呼び出され、フックコーラーインスタンス、HookImpl インスタンスのリスト、およびフック呼び出しのキーワード引数を受け取ります。

after(outcome, hook_name, hook_impls, kwargs) は before と同じ引数を受け取りますが、フック呼び出し全体の結果を表す Result オブジェクトも受け取ります。

add_hookspecs(module_or_class)¶

指定された module_or_class に定義された新しいフック仕様を追加します。

関数は、対応する HookspecMarker でデコレートされている場合にフック仕様として認識されます。

check_pending()¶

フック仕様に対して検証されていないすべてのフックがオプションであることを確認します。そうでない場合は PluginValidationError を発生させます。

enable_tracing()¶

フック呼び出しのトレースを有効にします。

呼び出されると、追加されたトレースを削除する元に戻す関数を返します。

get_canonical_name(plugin)¶

プラグインオブジェクトの正規名を返します。

プラグインは register(plugin, name) の呼び出し元によって指定された別の名前で登録される場合があることに注意してください。登録されたプラグインの名前を取得するには、代わりに get_name(plugin) を使用してください。

get_hookcallers(plugin)¶

指定されたプラグインのすべてのフックコーラーを取得します。

戻り値:: フックコーラー、または plugin がこのプラグインマネージャーに登録されていない場合は None。
戻り値の型:: list[HookCaller] | None

get_name(plugin)¶

プラグインが登録されている名前を返します。登録されていない場合は None。

get_plugin(name)¶

指定された名前で登録されているプラグインを返します（存在する場合）。

get_plugins()¶

登録されているすべてのプラグインオブジェクトのセットを返します。

has_plugin(name)¶

指定された名前のプラグインが登録されているかどうかを返します。

is_blocked(name)¶

指定されたプラグイン名がブロックされているかどうかを返します。

is_registered(plugin)¶

プラグインが既に登録されているかどうかを返します。

list_name_plugin()¶

すべての登録されたプラグインの (name, plugin) ペアのリストを返します。

list_plugin_distinfo()¶

すべての setuptools に登録されたプラグインの (plugin, distinfo) ペアのリストを返します。

load_setuptools_entrypoints(group, name=None)¶

指定された setuptools group をクエリしてモジュールをロードします。

パラメータ:

group (str) -- プラグインをロードするエントリーポイントグループ。
name (str | None) -- 指定された場合、指定された name のプラグインのみをロードします。

戻り値:

この呼び出しによってロードされたプラグインの数。

戻り値の型:

int

set_blocked(name)¶

指定された名前の登録をブロックし、既に登録されている場合は登録を解除します。

subset_hook_caller(name, remove_plugins)¶

名前付きメソッドのプロキシ HookCaller インスタンスを返します。このインスタンスは、remove_plugins からのものを除くすべての登録されたプラグインへの呼び出しを管理します。

unblock(name)¶

名前のブロックを解除します。

名前が実際にブロックされていたかどうかを返します。

unregister(plugin=None, name=None)¶

プラグインとそのすべてのフック実装の登録を解除します。

プラグインはプラグインオブジェクトまたはプラグイン名のいずれかで指定できます。両方が指定されている場合、それらは一致している必要があります。

登録解除されたプラグインを返します。見つからない場合は None。

project_name: Final¶: プロジェクト名。

hook: Final¶: フックリレー。すべての登録されたプラグインでフックを呼び出すために使用されます。詳細は Calling hooks を参照してください。

trace: Final[_tracing.TagTracerSub]¶: トレースエントリーポイント。詳細は Built-in tracing を参照してください。

TestReport¶

final class TestReport[ソース]¶

ベースクラス: BaseReport

基本的なテストレポートオブジェクト（セットアップおよびティアダウン呼び出しが失敗した場合にも使用されます）。

レポートには任意の追加属性を含めることができます。

nodeid: str¶: 正規化されたコレクション nodeid。

location: tuple[str, int | None, str]¶: テストアイテムの実際の場所を示す (filesystempath, lineno, domaininfo) タプル。メソッドが異なるモジュールから継承されている場合など、収集された場所と異なる場合があります。 filesystempath は config.rootdir に対して相対的である場合があります。行番号は 0 ベースです。

keywords: Mapping[str, Any]¶: テスト呼び出しに関連付けられたすべてのキーワードおよびマーカーを含む名前 -> 値の辞書。

outcome: Literal['passed', 'failed', 'skipped']¶: テストの結果。常に "passed"、"failed"、"skipped" のいずれか。

longrepr: None | ExceptionInfo[BaseException] | tuple[str, int, str] | str | TerminalRepr¶: None または失敗の表現。

when: str | None¶: runtest フェーズを示す 'setup'、'call'、'teardown' のいずれか。

user_properties¶: ユーザープロパティは、テストのユーザー定義プロパティを保持する (name, value) タプルのリストです。

sections: list[tuple[str, str]]¶: テストレポートの追加情報を含む (heading, content) の文字列タプル。 pytest は stdout、stderr からキャプチャされたテキストやインターセプトされたログイベントを追加するために使用します。他のプラグインがレポートに任意の情報を追加するために使用することもできます。

duration: float¶: テストの実行にかかった時間。

start: float¶: 呼び出しが開始されたシステム時刻（エポックからの秒数）。

stop: float¶: 呼び出しが終了したシステム時刻（エポックからの秒数）。

classmethod from_item_and_call(item, call)[ソース]¶

標準のアイテムおよび呼び出し情報で TestReport を作成して埋めます。

パラメータ:

item (Item) -- アイテム。
call (CallInfo[None]) -- 呼び出し情報。

property caplog: str¶: ログキャプチャが有効な場合、キャプチャされたログ行を返します。

Added in version 3.5.

property capstderr: str¶: キャプチャが有効な場合、stderr からキャプチャされたテキストを返します。

Added in version 3.0.

property capstdout: str¶: キャプチャが有効な場合、stdout からキャプチャされたテキストを返します。

Added in version 3.0.

property count_towards_summary: bool¶: 実験的 このレポートがテストセッションの最後に表示される合計（"1 passed, 1 failure" など）にカウントされるかどうか。

注釈

この関数は 実験的 と見なされているため、パッチリリースでも変更される可能性があることに注意してください。

property failed: bool¶: 結果が失敗したかどうか。

property fspath: str¶: 報告されたノードのパス部分（文字列として）。

property head_line: str | None¶

実験的 このレポートの longrepr 出力に表示されるヘッドライン。通常は失敗時のトレースバック表現中に表示されます：

________ Test.foo ________

上記の例では、ヘッドラインは "Test.foo" です。

注釈

この関数は 実験的 と見なされているため、パッチリリースでも変更される可能性があることに注意してください。

property longreprtext: str¶: longrepr の完全な文字列表現を返す読み取り専用プロパティ。

Added in version 3.0.

property passed: bool¶: 結果が成功したかどうか。

property skipped: bool¶: 結果がスキップされたかどうか。

TestShortLogReport¶

class TestShortLogReport[ソース]¶

テストステータス結果カテゴリ、短い文字、および詳細な単語を格納するために使用されます。例えば "rerun", "R", ("RERUN", {"yellow": True})。

変数:

category -- 結果のクラス。例えば “passed”、“skipped”、“error”、または空文字列。
letter -- テストの進行中に表示される短い文字。例えば "."、"s"、"E"、または空文字列。
word -- 詳細モードでテストの進行中に表示される詳細な単語。例えば "PASSED"、"SKIPPED"、"ERROR"、または空文字列。

category: str¶: フィールド番号 0 のエイリアス

letter: str¶: フィールド番号 1 のエイリアス

word: str | tuple[str, Mapping[str, bool]]¶: フィールド番号 2 のエイリアス

Result¶

hook wrappers 内で使用される結果オブジェクト。詳細は Result in the pluggy documentation を参照してください。

Stash¶

class Stash[ソース]¶

Stash は型安全な異種可変マッピングであり、キーと値のタイプを Stash が作成される場所とは別に定義できます。

通常、Stash を持つオブジェクトが与えられます。例えば Config または Node：

stash: Stash = some_object.stash

モジュールまたはプラグインがこの Stash にデータを保存したい場合、キーのために StashKeys を作成します（モジュールレベルで）：

# At the top-level of the module
some_str_key = StashKey[str]()
some_bool_key = StashKey[bool]()

情報を保存するには：

# Value type must match the key.
stash[some_str_key] = "value"
stash[some_bool_key] = True

情報を取得するには：

# The static type of some_str is str.
some_str = stash[some_str_key]
# The static type of some_bool is bool.
some_bool = stash[some_bool_key]

Added in version 7.0.

__setitem__(key, value)[ソース]¶

キーの値を設定します。

__getitem__(key)[ソース]¶

キーの値を取得します。

キーが以前に設定されていなかった場合、KeyError を発生させます。

get(key, default)[ソース]¶

キーの値を取得します。キーが以前に設定されていなかった場合、デフォルトを返します。

setdefault(key, default)[ソース]¶

既に設定されている場合はキーの値を返し、そうでない場合はキーの値をデフォルトに設定してデフォルトを返します。

__delitem__(key)[ソース]¶

キーの値を削除します。

キーが以前に設定されていなかった場合、KeyError を発生させます。

__contains__(key)[ソース]¶

キーが設定されているかどうかを返します。

__len__()[ソース]¶

スタッシュに存在するアイテムの数を返します。

class StashKey[ソース]¶

ベースクラス: Generic[T]

StashKey は Stash のキーとして使用されるオブジェクトです。

StashKey はキーの値のタイプ T に関連付けられています。

StashKey は一意であり、他のキーと競合することはありません。

Added in version 7.0.

グローバル変数¶

pytest は、テストモジュールや conftest.py ファイルで定義された一部のグローバル変数を特別に扱います。

collect_ignore¶

チュートリアル：テスト収集のカスタマイズ

conftest.py ファイル に宣言してテストディレクトリやモジュールを除外できます。パスのリスト（str、pathlib.Path または任意の os.PathLike）である必要があります。

collect_ignore = ["setup.py"]

collect_ignore_glob¶

チュートリアル：テスト収集のカスタマイズ

conftest.py ファイル に宣言して Unix シェルスタイルのワイルドカードを使用してテストディレクトリやモジュールを除外できます。 str にグロブパターンを含むことができる list[str] である必要があります。

collect_ignore_glob = ["*_ignore.py"]

pytest_plugins¶

チュートリアル：テストモジュールまたは conftest ファイルでのプラグインの要求/読み込み

テストモジュール および conftest.py ファイル の グローバル レベルで宣言して追加のプラグインを登録できます。 str または Sequence[str] のいずれかです。

pytest_plugins = "myapp.testsupport.myplugin"

pytest_plugins = ("myapp.testsupport.tools", "myapp.testsupport.regression")

pytestmark¶

チュートリアル：クラス全体またはモジュールにマークを付ける

テストモジュール の グローバル レベルで宣言して、すべてのテスト関数およびメソッドに 1 つ以上の marks を適用できます。単一のマークまたはマークのリスト（左から右の順に適用）である場合があります。

import pytest

pytestmark = pytest.mark.webtest

import pytest

pytestmark = [pytest.mark.integration, pytest.mark.slow]

環境変数¶

pytest の動作を変更するために使用できる環境変数。

CI¶

設定されている場合（値に関係なく）、pytest は CI プロセスで実行されていることを認識します。 BUILD_NUMBER 変数の代替です。詳細は CI パイプラインを参照してください。

BUILD_NUMBER¶

設定されている場合（値に関係なく）、pytest は CI プロセスで実行されていることを認識します。 CI 変数の代替です。詳細は CI パイプラインを参照してください。

PYTEST_ADDOPTS¶

これには、ユーザーが指定したコマンドラインに 先頭に追加 されるコマンドライン（py:mod:shlex モジュールによって解析されます）が含まれます。詳細は組み込み設定ファイルオプションを参照してください。

PYTEST_VERSION¶

この環境変数は pytest セッションの開始時に定義され、その後は未定義になります。 pytest.__version__ の値を含み、他のこととともに、コードが pytest 実行中に実行されているかどうかを簡単に確認するために使用できます。

PYTEST_CURRENT_TEST¶

これはユーザーによって設定されることを意図しているのではなく、pytest が内部的に現在のテストの名前で設定します。他のプロセスがそれを検査できるようにします。詳細は PYTEST_CURRENT_TEST 環境変数を参照してください。

PYTEST_DEBUG¶

設定されている場合、pytest はトレースおよびデバッグ情報を出力します。

PYTEST_DEBUG_TEMPROOT¶

tmp_path のようなフィクスチャによって生成される一時ディレクトリのルート。詳細は一時ディレクトリの場所と保持を参照してください。

PYTEST_DISABLE_PLUGIN_AUTOLOAD¶

設定されている場合、entry point packaging metadata を通じたプラグインの自動読み込みを無効にします。明示的に指定されたプラグインのみが読み込まれます。

PYTEST_PLUGINS¶

プラグインとして読み込むべきモジュールのカンマ区切りリストを含みます：

export PYTEST_PLUGINS=mymodule.plugin,xdist

PYTEST_THEME¶

コード出力に使用する pygment style を設定します。

PYTEST_THEME_MODE¶

PYTEST_THEME を dark または light に設定します。

PY_COLORS¶

1 に設定すると、pytest はターミナル出力に色を使用します。 0 に設定すると、pytest は色を使用しません。 PY_COLORS は NO_COLOR および FORCE_COLOR より優先されます。

NO_COLOR¶

空でない文字列に設定されている場合（値に関係なく）、pytest はターミナル出力に色を使用しません。 PY_COLORS は NO_COLOR より優先され、FORCE_COLOR より優先されます。詳細は no-color.org を参照してください。このコミュニティ標準をサポートする他のライブラリについても説明しています。

FORCE_COLOR¶

空でない文字列に設定されている場合（値に関係なく）、pytest はターミナル出力に色を使用します。 PY_COLORS および NO_COLOR は FORCE_COLOR より優先されます。

例外¶

final exception UsageError[ソース]¶

ベースクラス: Exception

pytest の使用または呼び出しに関するエラー。

final exception FixtureLookupError[ソース]¶

ベースクラス: LookupError

要求されたフィクスチャを返すことができませんでした（存在しないか無効です）。

警告¶

不適切な使用や非推奨の機能などの状況で生成されるカスタム警告。

class PytestWarning¶

ベースクラス: UserWarning

pytest によって発行されるすべての警告の基本クラス。

class PytestAssertRewriteWarning¶

ベースクラス: PytestWarning

pytest アサートリライトモジュールによって発行される警告。

class PytestCacheWarning¶

ベースクラス: PytestWarning

さまざまな状況でキャッシュプラグインによって発行される警告。

class PytestCollectionWarning¶

ベースクラス: PytestWarning

pytest がファイルまたはモジュール内のシンボルを収集できない場合に発行される警告。

class PytestConfigWarning¶

ベースクラス: PytestWarning

設定の問題に対して発行される警告。

class PytestDeprecationWarning¶

ベースクラス: PytestWarning, DeprecationWarning

将来のバージョンで削除される機能の警告クラス。

class PytestExperimentalApiWarning¶

ベースクラス: PytestWarning, FutureWarning

pytest の実験を示すために使用される警告カテゴリ。

API は将来のバージョンで変更されたり、完全に削除されたりする可能性があるため、慎重に使用してください。

class PytestReturnNotNoneWarning¶

ベースクラス: PytestWarning

テスト関数が None 以外の値を返しているときに発行される警告。

class PytestRemovedIn9Warning¶

ベースクラス: PytestDeprecationWarning

pytest 9 で削除される機能の警告クラス。

class PytestUnhandledCoroutineWarning¶

ベースクラス: PytestReturnNotNoneWarning

未処理のコルーチンに対して発行される警告。

テスト関数を収集する際にコルーチンが見つかりましたが、非同期対応プラグインによって処理されませんでした。コルーチンテスト関数はネイティブにはサポートされていません。

class PytestUnknownMarkWarning¶

ベースクラス: PytestWarning

未知のマーカーの使用時に発行される警告。

詳細はテスト関数に属性をマークする方法を参照してください。

class PytestUnraisableExceptionWarning¶

ベースクラス: PytestWarning

報告された未発生の例外。

未発生の例外は、__del__ 実装や、例外を通常の方法で発生させることができない状況で発生する例外です。

class PytestUnhandledThreadExceptionWarning¶

ベースクラス: PytestWarning

An unhandled exception occurred in a Thread.

このような例外は通常の方法では伝播しません。

詳細については、ドキュメントの内部 pytest 警告セクションを参照してください。

設定オプション¶

ここに、通常リポジトリのルートに配置される pytest.ini (または .pytest.ini)、pyproject.toml、tox.ini、setup.cfg ファイルに記述できる組み込みの設定オプションのリストがあります。

各ファイル形式の詳細については、設定ファイル形式を参照してください。

警告

非常に単純な使用例を除いて、setup.cfg の使用は推奨されません。 .cfg ファイルは pytest.ini や tox.ini とは異なるパーサーを使用するため、問題の追跡が困難になる可能性があります。可能であれば、後者のファイルや pyproject.toml を使用して pytest の設定を保持することをお勧めします。

設定オプションは、コマンドラインで -o/--override-ini を使用して上書きすることができ、複数回渡すこともできます。期待される形式は name=value です。例えば:

pytest -o console_output_style=classic -o cache_dir=/tmp/mycache

addopts¶

指定された OPTS をコマンドライン引数のセットに追加します。ユーザーが指定したかのように。例: この ini ファイルの内容がある場合:

# content of pytest.ini
[pytest]
addopts = --maxfail=2 -rf  # exit after 2 failures, report fail info

pytest test_hello.py を発行することは実際には次の意味です:

pytest --maxfail=2 -rf test_hello.py

デフォルトではオプションを追加しません。

cache_dir¶: キャッシュプラグインの内容が保存されるディレクトリを設定します。デフォルトのディレクトリは rootdir に作成される .pytest_cache です。ディレクトリは相対パスまたは絶対パスで指定できます。相対パスを設定する場合、ディレクトリは rootdir に対して相対的に作成されます。さらに、パスには環境変数を含めることができ、展開されます。キャッシュプラグインの詳細については、失敗したテストを再実行し、テスト実行間で状態を維持する方法を参照してください。

consider_namespace_packages¶

Python モジュールを収集する際に pytest が namespace packages を識別しようとするかどうかを制御します。デフォルトは False です。

テストしているパッケージがネームスペースパッケージの一部である場合は True に設定します。

サポートされているのは native namespace packages のみであり、legacy namespace packages をサポートする予定はありません。

Added in version 8.1.

console_output_style¶

テスト実行中のコンソール出力スタイルを設定します:

classic: クラシックな pytest 出力。
progress: クラシックな pytest 出力に似ていますが、進行状況インジケーターが追加されています。
progress-even-when-capture-no: capture=no の場合でも進行状況インジケーターの使用を許可します。
count: 進行状況に似ていますが、パーセントではなく完了したテストの数として進行状況を表示します。

デフォルトは progress ですが、好みに応じて、または新しいモードが予期しない問題を引き起こしている場合は classic に戻すことができます:

# content of pytest.ini
[pytest]
console_output_style = classic

doctest_encoding¶: ドックストリングを含むテキストファイルをデコードするために使用するデフォルトのエンコーディング。 See how pytest handles doctests を参照してください。

doctest_optionflags¶: 標準の doctest モジュールからの 1 つ以上のドックテストフラグ名。 See how pytest handles doctests を参照してください。

empty_parameter_set_mark¶

パラメータ化で空のパラメータセットに対するアクションを選択できます

skip は空のパラメータセットを持つテストをスキップします (デフォルト)
xfail は空のパラメータセットを持つテストを xfail(run=False) としてマークします
fail_at_collect は、パラメータ化が空のパラメータセットを収集した場合に例外を発生させます

# content of pytest.ini
[pytest]
empty_parameter_set_mark = xfail

注釈

このオプションのデフォルト値は、将来のリリースで xfail に変更される予定です。これはエラーが発生しにくいと考えられるためです。詳細については #3155 を参照してください。

faulthandler_timeout¶

テストの実行に X 秒以上かかる場合 (フィクスチャのセットアップとティアダウンを含む)、すべてのスレッドのトレースバックをダンプします。 faulthandler.dump_traceback_later() 関数を使用して実装されているため、そこにあるすべての注意事項が適用されます。

# content of pytest.ini
[pytest]
faulthandler_timeout=5

詳細についてはフォールトハンドラーを参照してください。

filterwarnings¶

一致する警告に対して実行されるフィルターとアクションのリストを設定します。デフォルトでは、テストセッション中に発生したすべての警告がテストセッションの最後に要約として表示されます。

# content of pytest.ini
[pytest]
filterwarnings =
    error
    ignore::DeprecationWarning

これは pytest に非推奨警告を無視し、他のすべての警告をエラーに変えるように指示します。詳細については警告をキャプチャする方法を参照してください。

junit_duration_report¶

Added in version 4.1.

JUnit XML レポートに期間が記録される方法を設定します:

total (デフォルト): 報告される期間にはセットアップ、呼び出し、およびティアダウンの時間が含まれます。
call: 報告される期間にはセットアップとティアダウンを除く呼び出し時間のみが含まれます。

[pytest]
junit_duration_report = call

junit_family¶

Added in version 4.2.

バージョン 6.1 で変更: デフォルトが xunit2 に変更されました。

生成された JUnit XML ファイルの形式を設定します。可能なオプションは次のとおりです:

xunit1 (または legacy): xunit 1.0 形式と互換性のある古いスタイルの出力を生成します。
xunit2: xunit 2.0 スタイルの出力を生成します。これは最新の Jenkins バージョンとより互換性があるはずです。 これがデフォルトです。

[pytest]
junit_family = xunit2

junit_logging¶

Added in version 3.5.

バージョン 5.4 で変更: log、all、out-err オプションが追加されました。

キャプチャされた出力を JUnit XML ファイルに書き込むかどうかを設定します。有効な値は次のとおりです:

log: logging キャプチャされた出力のみを書き込みます。
system-out: キャプチャされた stdout の内容を書き込みます。
system-err: キャプチャされた stderr の内容を書き込みます。
out-err: キャプチャされた stdout と stderr の両方の内容を書き込みます。
all: キャプチャされた logging、stdout、stderr の内容を書き込みます。
no (デフォルト): キャプチャされた出力は書き込まれません。

[pytest]
junit_logging = system-out

junit_log_passing_tests¶

Added in version 4.6.

junit_logging != "no" の場合、成功した テストのキャプチャされた出力を JUnit XML ファイルに書き込むかどうかを設定します。デフォルトは True です。

[pytest]
junit_log_passing_tests = False

junit_suite_name¶

ルートテストスイート xml アイテムの名前を設定するには、設定ファイルで junit_suite_name オプションを設定できます:

[pytest]
junit_suite_name = my_suite

log_auto_indent¶

複数行のログメッセージの選択的な自動インデントを許可します。

すべてのログの自動インデント動作を設定するためのコマンドラインオプション --log-auto-indent [value] および設定オプション log_auto_indent = [value] をサポートします。

[value] は次の値にすることができます:

True または "On" - 複数行のログメッセージを動的に自動インデントします。
False または "Off" または 0 - 複数行のログメッセージを自動インデントしない (デフォルトの動作)
[正の整数] - 複数行のログメッセージを [value] スペースで自動インデント

[pytest]
log_auto_indent = False

ログに特定のエントリの自動インデント動作を指定するために logging.log() への呼び出しに kwarg extra={"auto_indent": [value]} を渡すことをサポートします。 extra kwarg はコマンドラインまたは設定で指定された値を上書きします。

log_cli¶

テスト実行中にログ表示を有効にします ("live logging" とも呼ばれます)。デフォルトは False です。

[pytest]
log_cli = True

log_cli_date_format¶

ライブロギングの日付をフォーマットする際に使用される time.strftime() 互換の文字列を設定します。

[pytest]
log_cli_date_format = %Y-%m-%d %H:%M:%S

詳細については、ライブログを参照してください。

log_cli_format¶

ライブロギングメッセージをフォーマットするために使用される logging 互換の文字列を設定します。

[pytest]
log_cli_format = %(asctime)s %(levelname)s %(message)s

詳細については、ライブログを参照してください。

log_cli_level¶

ライブロギングのためにキャプチャされる最小のログメッセージレベルを設定します。整数値またはレベルの名前を使用できます。

[pytest]
log_cli_level = INFO

詳細については、ライブログを参照してください。

log_date_format¶

ログキャプチャの日付をフォーマットする際に使用される time.strftime() 互換の文字列を設定します。

[pytest]
log_date_format = %Y-%m-%d %H:%M:%S

詳細については、ロギングを管理する方法を参照してください。

log_file¶

現在の作業ディレクトリに対して相対的なファイル名を設定し、ログメッセージを他のアクティブなロギング機能に加えてそのファイルに書き込みます。

[pytest]
log_file = logs/pytest-logs.txt

詳細については、ロギングを管理する方法を参照してください。

log_file_date_format¶

ログファイルの日付をフォーマットする際に使用される time.strftime() 互換の文字列を設定します。

[pytest]
log_file_date_format = %Y-%m-%d %H:%M:%S

詳細については、ロギングを管理する方法を参照してください。

log_file_format¶

ログファイルにリダイレクトされたログメッセージをフォーマットするために使用される logging 互換の文字列を設定します。

[pytest]
log_file_format = %(asctime)s %(levelname)s %(message)s

詳細については、ロギングを管理する方法を参照してください。

log_file_level¶

ログファイルにキャプチャされる最小のログメッセージレベルを設定します。整数値またはレベルの名前を使用できます。

[pytest]
log_file_level = INFO

詳細については、ロギングを管理する方法を参照してください。

log_format¶

キャプチャされたログメッセージをフォーマットするために使用される logging 互換の文字列を設定します。

[pytest]
log_format = %(asctime)s %(levelname)s %(message)s

詳細については、ロギングを管理する方法を参照してください。

log_level¶

ログキャプチャにキャプチャされる最小のログメッセージレベルを設定します。整数値またはレベルの名前を使用できます。

[pytest]
log_level = INFO

詳細については、ロギングを管理する方法を参照してください。

markers¶

--strict-markers または --strict コマンドライン引数が使用されている場合、コア pytest またはプラグインによってコードで定義された既知のマーカーのみが許可されます。

この設定で追加のマーカーをリストすることで、それらをホワイトリストに追加できます。この場合、将来のリグレッションを避けるために --strict-markers を addopts に追加することをお勧めします:

[pytest]
addopts = --strict-markers
markers =
    slow
    serial

注釈

--strict-markers の使用が強く推奨されます。 --strict は後方互換性のために保持されており、他のオプションには適用されず、マーカーにのみ適用されるため、他の人にとって混乱を招く可能性があります。

minversion¶

テストを実行するために必要な最小の pytest バージョンを指定します。

# content of pytest.ini
[pytest]
minversion = 3.0  # will fail if we run with pytest-2.8

norecursedirs¶

テスト検出のために再帰する際に避けるべきディレクトリのベース名パターンを設定します。個々の (fnmatch スタイル) パターンは、再帰するかどうかを決定するためにディレクトリのベース名に適用されます。パターンマッチング文字:

*       matches everything
?       matches any single character
[seq]   matches any character in seq
[!seq]  matches any char not in seq

デフォルトのパターンは '*.egg', '.*', '_darcs', 'build', 'CVS', 'dist', 'node_modules', 'venv', '{arch}' です。 norecursedirs を設定するとデフォルトが置き換えられます。ここに特定のディレクトリを避ける方法の例を示します:

[pytest]
norecursedirs = .svn _build tmp*

これは pytest に典型的なサブバージョンまたは sphinx-build ディレクトリや tmp プレフィックスのディレクトリを見ないように指示します。

さらに、pytest は仮想環境のルートと見なされるディレクトリを自動的に識別して無視しようとします。仮想環境のルートと見なされるディレクトリは、--collect-in-virtualenv が指定されない限り、テスト収集中に考慮されません。また、norecursedirs は --collect-in-virtualenv よりも優先されます。例えば、ベースディレクトリが '.*' に一致する仮想環境でテストを実行する場合、--collect-in-virtualenv フラグを使用するだけでなく、norecursedirs を上書きする必要があります。

python_classes¶

テスト収集のために考慮されるクラスを決定するための 1 つ以上の名前プレフィックスまたはグロブスタイルのパターン。パターン間にスペースを追加することで複数のグロブパターンを検索します。デフォルトでは、pytest は Test で始まるクラスをテスト収集として考慮します。ここに Suite で終わるクラスからテストを収集する方法の例を示します:

[pytest]
python_classes = *Suite

unittest.TestCase から派生したクラスは、このオプションに関係なく常に収集されます。これは unittest の独自の収集フレームワークを使用してこれらのテストを収集するためです。

python_files¶

テストモジュールとして考慮される Python ファイルを決定するための 1 つ以上のグロブスタイルのファイルパターン。パターン間にスペースを追加することで複数のグロブパターンを検索します:

[pytest]
python_files = test_*.py check_*.py example_*.py

または 1 行ごと:

[pytest]
python_files =
    test_*.py
    check_*.py
    example_*.py

デフォルトでは、test_*.py および *_test.py に一致するファイルがテストモジュールとして考慮されます。

python_functions¶

テスト関数およびメソッドとして考慮されるテスト関数およびメソッドを決定するための 1 つ以上の名前プレフィックスまたはグロブパターン。パターン間にスペースを追加することで複数のグロブパターンを検索します。デフォルトでは、pytest は test で始まる関数をテストとして考慮します。ここに _test で終わるテスト関数およびメソッドを収集する方法の例を示します:

[pytest]
python_functions = *_test

これは unittest.TestCase から派生したクラスのメソッドには影響しません。これは unittest の独自の収集フレームワークを使用してこれらのテストを収集するためです。

詳細な例については、命名規則の変更を参照してください。

pythonpath¶

Python の検索パスに追加するディレクトリのリストを設定します。ディレクトリは sys.path の先頭に追加されます。 PYTHONPATH 環境変数と同様に、ディレクトリは Python がインポートされたモジュールを探す場所に含まれます。パスは rootdir ディレクトリに対して相対的です。ディレクトリはテストセッションの期間中パスに残ります。

[pytest]
pythonpath = src1 src2

注釈

pythonpath は、特に -p コマンドラインオプションを使用してロードされるプラグインなど、非常に早い段階で発生する一部のインポートには影響しません。

required_plugins¶

pytest を実行するために存在しなければならないプラグインのスペース区切りリスト。プラグインはバージョン指定子を名前の直後に付けてリストすることができます。異なるバージョン指定子間に空白は許可されません。プラグインのいずれかが見つからない場合、エラーを発生させます。

[pytest]
required_plugins = pytest-django>=3.0.0,<4.0.0 pytest-html pytest-xdist>=1.0.0

testpaths¶

pytest を rootdir ディレクトリから実行する際に、コマンドラインで特定のディレクトリ、ファイル、またはテスト ID が指定されていない場合にテストを検索するディレクトリのリストを設定します。ファイルシステムパスはシェルスタイルのワイルドカードを使用できます。再帰的な ** パターンを含みます。

プロジェクトのすべてのテストが既知の場所にある場合、テスト収集を高速化し、誤って不要なテストを拾うのを避けるために便利です。

[pytest]
testpaths = testing doc

この構成は、次のコマンドを実行することを意味します:

pytest

次のコマンドを実行するのと同じ実際の効果があります:

pytest testing doc

tmp_path_retention_count¶

tmp_path_retention_policy に従って tmp_path ディレクトリをいくつのセッション保持するか。

[pytest]
tmp_path_retention_count = 3

デフォルト: 3

tmp_path_retention_policy¶

tmp_path フィクスチャによって作成されたディレクトリをテスト結果に基づいて保持するかどうかを制御します。

all: テスト結果に関係なく、すべてのテストのディレクトリを保持します。

failed: 結果が error または failed のテストのみディレクトリを保持します。

none: 結果に関係なく、各テスト終了後にディレクトリは常に削除されます。

[pytest]
tmp_path_retention_policy = all

デフォルト: all

usefixtures¶

すべてのテスト関数に適用されるフィクスチャのリスト。これは、すべてのテスト関数に @pytest.mark.usefixtures マーカーを適用するのと同じ意味です。

[pytest]
usefixtures =
    clean_db

verbosity_assertions¶

アサーション関連の出力に対して特定の詳細レベルを設定し、アプリケーション全体のレベルを上書きします。

[pytest]
verbosity_assertions = 2

デフォルトはアプリケーション全体の詳細レベル (-v コマンドラインオプションを介して) です。特別な値 auto を使用して、グローバルな詳細レベルを明示的に使用することができます。

verbosity_test_cases¶

テストケース実行関連の出力に対して特定の詳細レベルを設定し、アプリケーション全体のレベルを上書きします。

[pytest]
verbosity_test_cases = 2

xfail_strict¶

True に設定すると、実際に成功した @pytest.mark.xfail でマークされたテストはデフォルトでテストスイートに失敗します。詳細については、strict パラメータを参照してください。

[pytest]
xfail_strict = True

コマンドラインフラグ¶

すべてのコマンドラインフラグは pytest --help を実行することで取得できます:

$ pytest --help
usage: pytest [options] [file_or_dir] [file_or_dir] [...]

positional arguments:
  file_or_dir

general:
  -k EXPRESSION         Only run tests which match the given substring
                        expression. An expression is a Python evaluable
                        expression where all names are substring-matched
                        against test names and their parent classes.
                        Example: -k 'test_method or test_other' matches all
                        test functions and classes whose name contains
                        'test_method' or 'test_other', while -k 'not
                        test_method' matches those that don't contain
                        'test_method' in their names. -k 'not test_method
                        and not test_other' will eliminate the matches.
                        Additionally keywords are matched to classes and
                        functions containing extra names in their
                        'extra_keyword_matches' set, as well as functions
                        which have names assigned directly to them. The
                        matching is case-insensitive.
  -m MARKEXPR           Only run tests matching given mark expression. For
                        example: -m 'mark1 and not mark2'.
  --markers             show markers (builtin, plugin and per-project ones).
  -x, --exitfirst       Exit instantly on first error or failed test
  --fixtures, --funcargs
                        Show available fixtures, sorted by plugin appearance
                        (fixtures with leading '_' are only shown with '-v')
  --fixtures-per-test   Show fixtures per test
  --pdb                 Start the interactive Python debugger on errors or
                        KeyboardInterrupt
  --pdbcls=modulename:classname
                        Specify a custom interactive Python debugger for use
                        with --pdb.For example:
                        --pdbcls=IPython.terminal.debugger:TerminalPdb
  --trace               Immediately break when running each test
  --capture=method      Per-test capturing method: one of fd|sys|no|tee-sys
  -s                    Shortcut for --capture=no
  --runxfail            Report the results of xfail tests as if they were
                        not marked
  --lf, --last-failed   Rerun only the tests that failed at the last run (or
                        all if none failed)
  --ff, --failed-first  Run all tests, but run the last failures first. This
                        may re-order tests and thus lead to repeated fixture
                        setup/teardown.
  --nf, --new-first     Run tests from new files first, then the rest of the
                        tests sorted by file mtime
  --cache-show=[CACHESHOW]
                        Show cache contents, don't perform collection or
                        tests. Optional argument: glob (default: '*').
  --cache-clear         Remove all cache contents at start of test run
  --lfnf={all,none}, --last-failed-no-failures={all,none}
                        With ``--lf``, determines whether to execute tests
                        when there are no previously (known) failures or
                        when no cached ``lastfailed`` data was found.
                        ``all`` (the default) runs the full test suite
                        again. ``none`` just emits a message about no known
                        failures and exits successfully.
  --sw, --stepwise      Exit on test failure and continue from last failing
                        test next time
  --sw-skip, --stepwise-skip
                        Ignore the first failing test but stop on the next
                        failing test. Implicitly enables --stepwise.

Reporting:
  --durations=N         Show N slowest setup/test durations (N=0 for all)
  --durations-min=N     Minimal duration in seconds for inclusion in slowest
                        list. Default: 0.005.
  -v, --verbose         Increase verbosity
  --no-header           Disable header
  --no-summary          Disable summary
  --no-fold-skipped     Do not fold skipped tests in short summary.
  -q, --quiet           Decrease verbosity
  --verbosity=VERBOSE   Set verbosity. Default: 0.
  -r chars              Show extra test summary info as specified by chars:
                        (f)ailed, (E)rror, (s)kipped, (x)failed, (X)passed,
                        (p)assed, (P)assed with output, (a)ll except passed
                        (p/P), or (A)ll. (w)arnings are enabled by default
                        (see --disable-warnings), 'N' can be used to reset
                        the list. (default: 'fE').
  --disable-warnings, --disable-pytest-warnings
                        Disable warnings summary
  -l, --showlocals      Show locals in tracebacks (disabled by default)
  --no-showlocals       Hide locals in tracebacks (negate --showlocals
                        passed through addopts)
  --tb=style            Traceback print mode
                        (auto/long/short/line/native/no)
  --xfail-tb            Show tracebacks for xfail (as long as --tb != no)
  --show-capture={no,stdout,stderr,log,all}
                        Controls how captured stdout/stderr/log is shown on
                        failed tests. Default: all.
  --full-trace          Don't cut any tracebacks (default is to cut)
  --color=color         Color terminal output (yes/no/auto)
  --code-highlight={yes,no}
                        Whether code should be highlighted (only if --color
                        is also enabled). Default: yes.
  --pastebin=mode       Send failed|all info to bpaste.net pastebin service
  --junit-xml=path      Create junit-xml style report file at given path
  --junit-prefix=str    Prepend prefix to classnames in junit-xml output

pytest-warnings:
  -W PYTHONWARNINGS, --pythonwarnings=PYTHONWARNINGS
                        Set which warnings to report, see -W option of
                        Python itself
  --maxfail=num         Exit after first num failures or errors
  --strict-config       Any warnings encountered while parsing the `pytest`
                        section of the configuration file raise errors
  --strict-markers      Markers not registered in the `markers` section of
                        the configuration file raise errors
  --strict              (Deprecated) alias to --strict-markers
  -c FILE, --config-file=FILE
                        Load configuration from `FILE` instead of trying to
                        locate one of the implicit configuration files.
  --continue-on-collection-errors
                        Force test execution even if collection errors occur
  --rootdir=ROOTDIR     Define root directory for tests. Can be relative
                        path: 'root_dir', './root_dir',
                        'root_dir/another_dir/'; absolute path:
                        '/home/user/root_dir'; path with variables:
                        '$HOME/root_dir'.

collection:
  --collect-only, --co  Only collect tests, don't execute them
  --pyargs              Try to interpret all arguments as Python packages
  --ignore=path         Ignore path during collection (multi-allowed)
  --ignore-glob=path    Ignore path pattern during collection (multi-
                        allowed)
  --deselect=nodeid_prefix
                        Deselect item (via node id prefix) during collection
                        (multi-allowed)
  --confcutdir=dir      Only load conftest.py's relative to specified dir
  --noconftest          Don't load any conftest.py files
  --keep-duplicates     Keep duplicate tests
  --collect-in-virtualenv
                        Don't ignore tests in a local virtualenv directory
  --import-mode={prepend,append,importlib}
                        Prepend/append to sys.path when importing test
                        modules and conftest files. Default: prepend.
  --doctest-modules     Run doctests in all .py modules
  --doctest-report={none,cdiff,ndiff,udiff,only_first_failure}
                        Choose another output format for diffs on doctest
                        failure
  --doctest-glob=pat    Doctests file matching pattern, default: test*.txt
  --doctest-ignore-import-errors
                        Ignore doctest collection errors
  --doctest-continue-on-failure
                        For a given doctest, continue to run after the first
                        failure

test session debugging and configuration:
  --basetemp=dir        Base temporary directory for this test run.
                        (Warning: this directory is removed if it exists.)
  -V, --version         Display pytest version and information about
                        plugins. When given twice, also display information
                        about plugins.
  -h, --help            Show help message and configuration info
  -p name               Early-load given plugin module name or entry point
                        (multi-allowed). To avoid loading of plugins, use
                        the `no:` prefix, e.g. `no:doctest`.
  --trace-config        Trace considerations of conftest.py files
  --debug=[DEBUG_FILE_NAME]
                        Store internal tracing debug information in this log
                        file. This file is opened with 'w' and truncated as
                        a result, care advised. Default: pytestdebug.log.
  -o OVERRIDE_INI, --override-ini=OVERRIDE_INI
                        Override ini option with "option=value" style, e.g.
                        `-o xfail_strict=True -o cache_dir=cache`.
  --assert=MODE         Control assertion debugging tools.
                        'plain' performs no assertion debugging.
                        'rewrite' (the default) rewrites assert statements
                        in test modules on import to provide assert
                        expression information.
  --setup-only          Only setup fixtures, do not execute tests
  --setup-show          Show setup of fixtures while executing tests
  --setup-plan          Show what fixtures and tests would be executed but
                        don't execute anything

logging:
  --log-level=LEVEL     Level of messages to catch/display. Not set by
                        default, so it depends on the root/parent log
                        handler's effective level, where it is "WARNING" by
                        default.
  --log-format=LOG_FORMAT
                        Log format used by the logging module
  --log-date-format=LOG_DATE_FORMAT
                        Log date format used by the logging module
  --log-cli-level=LOG_CLI_LEVEL
                        CLI logging level
  --log-cli-format=LOG_CLI_FORMAT
                        Log format used by the logging module
  --log-cli-date-format=LOG_CLI_DATE_FORMAT
                        Log date format used by the logging module
  --log-file=LOG_FILE   Path to a file when logging will be written to
  --log-file-mode={w,a}
                        Log file open mode
  --log-file-level=LOG_FILE_LEVEL
                        Log file logging level
  --log-file-format=LOG_FILE_FORMAT
                        Log format used by the logging module
  --log-file-date-format=LOG_FILE_DATE_FORMAT
                        Log date format used by the logging module
  --log-auto-indent=LOG_AUTO_INDENT
                        Auto-indent multiline messages passed to the logging
                        module. Accepts true|on, false|off or an integer.
  --log-disable=LOGGER_DISABLE
                        Disable a logger by name. Can be passed multiple
                        times.

[pytest] ini-options in the first pytest.ini|tox.ini|setup.cfg|pyproject.toml file found:

  markers (linelist):   Register new markers for test functions
  empty_parameter_set_mark (string):
                        Default marker for empty parametersets
  norecursedirs (args): Directory patterns to avoid for recursion
  testpaths (args):     Directories to search for tests when no files or
                        directories are given on the command line
  filterwarnings (linelist):
                        Each line specifies a pattern for
                        warnings.filterwarnings. Processed after
                        -W/--pythonwarnings.
  consider_namespace_packages (bool):
                        Consider namespace packages when resolving module
                        names during import
  usefixtures (args):   List of default fixtures to be used with this
                        project
  python_files (args):  Glob-style file patterns for Python test module
                        discovery
  python_classes (args):
                        Prefixes or glob names for Python test class
                        discovery
  python_functions (args):
                        Prefixes or glob names for Python test function and
                        method discovery
  disable_test_id_escaping_and_forfeit_all_rights_to_community_support (bool):
                        Disable string escape non-ASCII characters, might
                        cause unwanted side effects(use at your own risk)
  console_output_style (string):
                        Console output: "classic", or with additional
                        progress information ("progress" (percentage) |
                        "count" | "progress-even-when-capture-no" (forces
                        progress even when capture=no)
  verbosity_test_cases (string):
                        Specify a verbosity level for test case execution,
                        overriding the main level. Higher levels will
                        provide more detailed information about each test
                        case executed.
  xfail_strict (bool):  Default for the strict parameter of xfail markers
                        when not given explicitly (default: False)
  tmp_path_retention_count (string):
                        How many sessions should we keep the `tmp_path`
                        directories, according to
                        `tmp_path_retention_policy`.
  tmp_path_retention_policy (string):
                        Controls which directories created by the `tmp_path`
                        fixture are kept around, based on test outcome.
                        (all/failed/none)
  enable_assertion_pass_hook (bool):
                        Enables the pytest_assertion_pass hook. Make sure to
                        delete any previously generated pyc cache files.
  verbosity_assertions (string):
                        Specify a verbosity level for assertions, overriding
                        the main level. Higher levels will provide more
                        detailed explanation when an assertion fails.
  junit_suite_name (string):
                        Test suite name for JUnit report
  junit_logging (string):
                        Write captured log messages to JUnit report: one of
                        no|log|system-out|system-err|out-err|all
  junit_log_passing_tests (bool):
                        Capture log information for passing tests to JUnit
                        report:
  junit_duration_report (string):
                        Duration time to report: one of total|call
  junit_family (string):
                        Emit XML for schema: one of legacy|xunit1|xunit2
  doctest_optionflags (args):
                        Option flags for doctests
  doctest_encoding (string):
                        Encoding used for doctest files
  cache_dir (string):   Cache directory path
  log_level (string):   Default value for --log-level
  log_format (string):  Default value for --log-format
  log_date_format (string):
                        Default value for --log-date-format
  log_cli (bool):       Enable log display during test run (also known as
                        "live logging")
  log_cli_level (string):
                        Default value for --log-cli-level
  log_cli_format (string):
                        Default value for --log-cli-format
  log_cli_date_format (string):
                        Default value for --log-cli-date-format
  log_file (string):    Default value for --log-file
  log_file_mode (string):
                        Default value for --log-file-mode
  log_file_level (string):
                        Default value for --log-file-level
  log_file_format (string):
                        Default value for --log-file-format
  log_file_date_format (string):
                        Default value for --log-file-date-format
  log_auto_indent (string):
                        Default value for --log-auto-indent
  pythonpath (paths):   Add paths to sys.path
  faulthandler_timeout (string):
                        Dump the traceback of all threads if a test takes
                        more than TIMEOUT seconds to finish
  addopts (args):       Extra command line options
  minversion (string):  Minimally required pytest version
  required_plugins (args):
                        Plugins that must be present for pytest to run

Environment variables:
  CI                       When set (regardless of value), pytest knows it is running in a CI process and does not truncate summary info
  BUILD_NUMBER             Equivalent to CI
  PYTEST_ADDOPTS           Extra command line options
  PYTEST_PLUGINS           Comma-separated plugins to load during startup
  PYTEST_DISABLE_PLUGIN_AUTOLOAD Set to disable plugin auto-loading
  PYTEST_DEBUG             Set to enable debug tracing of pytest's internals


to see available markers type: pytest --markers
to see available fixtures type: pytest --fixtures
(shown according to specified file_or_dir or current dir if not specified; fixtures with leading '_' are only shown with the '-v' option

API リファレンス¶

定数¶

pytest.__version__¶

pytest.version_tuple¶

関数¶

pytest.approx¶

pytest.fail¶

pytest.skip¶

pytest.importorskip¶

pytest.xfail¶

pytest.exit¶

pytest.main¶

pytest.param¶

pytest.raises¶

pytest.deprecated_call¶

pytest.register_assert_rewrite¶

pytest.warns¶

pytest.freeze_includes¶

マーク¶

pytest.mark.filterwarnings¶

pytest.mark.parametrize¶

pytest.mark.skip¶

pytest.mark.skipif¶

pytest.mark.usefixtures¶

pytest.mark.xfail¶

カスタムマーク¶

フィクスチャ¶

@pytest.fixture¶

capfd¶

capfdbinary¶

caplog¶

capsys¶

capsysbinary¶

config.cache¶

doctest_namespace¶

monkeypatch¶

pytestconfig¶

pytester¶

record_property¶

record_testsuite_property¶

recwarn¶

request¶

testdir¶

tmp_path¶

tmp_path_factory¶

tmpdir¶

tmpdir_factory¶

フック¶

@pytest.hookimpl¶

@pytest.hookspec¶

ブートストラップフック¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

初期化フック¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

コレクションフック¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

テスト実行（runtest）フック¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

conftest プラグインで使用する¶

pytest.version¶