`test` --- Python の回帰テストパッケージ¶

注釈

test パッケージは Python 内部での使用のみを目的としています。このドキュメントは Python のコア開発者向けに用意されています。ここで説明するコードは Python のリリース間で予告なく変更または削除される可能性があるため、Python の標準ライブラリ以外でこのパッケージを使うことは推奨しません。

test パッケージには Python のすべての回帰テストと、test.support および test.regrtest モジュールが含まれます。 test.support はテストの機能を補助し、test.regrtest はテストスイートを実行します。

test パッケージで名前が test_ から始まる各モジュールは、特定のモジュールや機能のテストスイートです。新しいテストはすべて unittest または doctest モジュールを使って記述してください。古いテストの一部は、sys.stdout に出力された内容を比較する「従来の」スタイルで記述されていますが、この形式のテストは非推奨です。

参考

unittest モジュール: PyUnit 回帰テストを書く。
doctest モジュール: ドキュメンテーション文字列に埋め込まれたテスト。

`test` パッケージの単体テストを書く¶

unittest モジュールを使ってテストを書く場合、幾つかのガイドラインに従うことが推奨されます。 1つは、テストモジュールの名前を、 test_ で始め、テスト対象となるモジュール名で終えることです。テストモジュール中のテストメソッドは名前を test_ で始めて、そのメソッドが何をテストしているかという説明で終えます。これはテスト実行プログラムが、そのメソッドをテストメソッドとして認識するために必要です。また、テストメソッドにはドキュメンテーション文字列を入れるべきではありません。コメント（例えば # 関数が True または False だけを返すことをテストする ）を使用して、テストメソッドのドキュメントを記述してください。ドキュメンテーション文字列があると、その内容が出力され、どのテストを実行しているかが表示されなくなるためです。

以下のような決まり文句を使います:

import unittest
from test import support

class MyTestCase1(unittest.TestCase):

    # setUp() と tearDown() は必要な場合だけ使う

    def setUp(self):
        ... code to execute in preparation for tests ...

    def tearDown(self):
        ... code to execute to clean up after tests ...

    def test_feature_one(self):
        # 機能その1をテストする
        ... testing code ...

    def test_feature_two(self):
        # 機能その2をテストする
        ... testing code ...

    ... more test methods ...

class MyTestCase2(unittest.TestCase):
    ... same structure as MyTestCase1 ...

... more test classes ...

if __name__ == '__main__':
    unittest.main()

このコードのパターンを使うと test.regrtest からテストスイートを実行でき、 unittest のコマンドラインインターフェースをサポートしているスクリプトとして自分自身を起動したり、 python -m unittest というコマンドラインインターフェースを通して起動したりできます。

回帰テストの目的は、コードが正しく動作しないケースを見つけることです。そのため、以下のガイドラインに従ってください。

テストスイートから、すべてのクラス、関数および定数を実行するべきです。これには外部に公開される外部APIだけでなく「プライベートな」コードも含みます。
ホワイトボックス・テスト（対象のコードの詳細を元にテストを書くこと）を推奨します。ブラックボックス・テスト（公開されるインターフェース仕様だけをテストすること）は、すべての境界条件を確実にテストするには完全ではありません。
すべての取りうる値を、無効値も含めてテストするようにしてください。そのようなテストを書くことで、全ての有効値が通るだけでなく、不適切な値が正しく処理されることも確認できます。
コード内のできる限り多くのパスを網羅してください。分岐するように入力を調整したテストを書くことで、コードの多くのパスをたどることができます。
テスト対象のコードにバグが発見された場合は、明示的にテスト追加するようにしてください。そのようなテストを追加することで、将来コードを変更した際にエラーが再発することを防止できます。
テストの後始末 (例えば一時ファイルをすべて閉じたり削除したりすること) を必ず行ってください。
テストがオペレーティングシステムの特定の状況に依存する場合、テスト開始時に条件を満たしているかを検証してください。
インポートするモジュールをできるかぎり少なくし、可能な限り早期にインポートを行ってください。そうすることで、テストの外部依存性を最小限にし、モジュールのインポートによる副作用から生じる変則的な動作を最小限にできます。
コードをできる限り再利用してください。テスト同士の違いが、使う入力の型といった小さな点だけということもあります。以下のように、基本となるテストクラスを継承し、サブクラスで入力を指定することで、コードの重複を最小限に抑えてください。
```
class TestFuncAcceptsSequencesMixin:

    func = mySuperWhammyFunction

    def test_func(self):
        self.func(self.arg)

class AcceptLists(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = [1, 2, 3]

class AcceptStrings(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = 'abc'

class AcceptTuples(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = (1, 2, 3)
```
このパターンを使うときは、unittest.TestCase を継承するクラスがすべてテストとして実行されることに注意してください。上の例の TestFuncAcceptsSequencesMixin クラスにはデータがなく、単独では実行できないため、unittest.TestCase を継承していません。

参考

Test Driven Development: コードより前にテストを書く方法論に関する Kent Beck の著書。

コマンドラインインターフェースを利用してテストを実行する¶

-m オプションを使うと、test パッケージを python -m test のようにスクリプトとして実行し、Python の回帰テストスイートを動かせます。内部では test.regrtest を使っており、以前の Python で使われていた python -m test.regrtest という呼び出し方も引き続き利用できます。スクリプトを引数なしで実行すると、test パッケージ内のすべての回帰テストが自動的に実行されます。名前が test_ で始まるモジュールとパッケージを探し、それぞれをインポートして unittest.TestLoader.loadTestsFromModule() でテストを読み込みます。読み込むテストをモジュールやパッケージでカスタマイズする方法については、load_tests プロトコルを参照してください。モジュールレベルの test_main() 関数の定義はサポートされておらず、テストが失敗します。実行するテストの名前をスクリプトに渡すこともできます。回帰テストを 1 つだけ指定すると (python -m test test_spam)、出力が最小限になり、テストが成功したか失敗したかだけが表示されます。

test を直接実行すると、テストで利用できるリソースを指定できます。これにはコマンドラインオプション -u を使います。 -u オプションの値に all を指定すると、すべてのリソースが有効になります (python -m test -uall)。一部のリソースだけを除外したい場合 (こちらの方が一般的です) は、all の後に不要なリソースをカンマで区切って指定できます。 python -m test -uall,-audio,-largefile は、audio と largefile 以外のすべてのリソースを有効にして test を実行します。すべてのリソースとその他のコマンドラインオプションを確認するには、python -m test -h を実行してください。

テストを実行しようとするプラットフォームによっては、回帰テストを実行する別の方法があります。 Unix では、Python をビルドしたトップレベルディレクトリで make test を実行できます。 Windows上では、 PCbuild ディレクトリから rt.bat を実行すると、すべての回帰テストを実行します。

Added in version 3.14: 出力はデフォルトで色付きになり、環境変数で制御できます。

`test.support` --- Python テストスイート用のユーティリティ¶

test.support モジュールは Python の回帰テストスイートを支援する機能を提供します。

注釈

test.support は公開モジュールではありません。このドキュメントは Python 開発者によるテストの作成を支援するためのものです。このモジュールの API は、リリース間で後方互換性を考慮せずに変更される場合があります。

このモジュールは次の例外を定義しています:

exception test.support.TestFailed¶: テストが失敗したときに送出する例外です。この例外は非推奨です。代わりに unittest に基づくテストと unittest.TestCase のアサーションメソッドを使ってください。

exception test.support.ResourceDenied¶: unittest.SkipTest のサブクラスです。 (ネットワーク接続のような) リソースが利用できないとき送出されます。 requires() 関数によって送出されます。

test.support モジュールは次の定数を定義しています。

test.support.verbose¶: 冗長な出力が有効な場合は True です。実行中のテストについてのより詳細な情報が欲しいときにチェックします。 verbose は test.regrtest によって設定されます。

test.support.is_jython¶: 実行中のインタプリタが Jython ならば True になります。

test.support.is_android¶: sys.platform が android の場合は True です。

test.support.is_emscripten¶: sys.platform が emscripten の場合は True です。

test.support.is_wasi¶: sys.platform が wasi の場合は True です。

test.support.is_apple_mobile¶: sys.platform が ios、tvos、watchos のいずれかの場合は True です。

test.support.is_apple¶: sys.platform が darwin、または is_apple_mobile が True の場合は True です。

test.support.unix_shell¶: Windows 以外ではシェルのパスです; そうでない場合は None です。

test.support.LOOPBACK_TIMEOUT¶

127.0.0.1 などのローカルループバックインターフェースで待ち受けるネットワークサーバーを使うテストの、秒単位のタイムアウトです。

このタイムアウトは、テストの失敗を防ぐのに十分な長さになっています。クライアントとサーバーが別のスレッドや別のプロセスで動作する可能性を考慮しています。

このタイムアウトは socket.socket の connect()、recv()、send() メソッドに対して十分な長さであるはずです。

デフォルト値は 10 秒です。

INTERNET_TIMEOUT も参照してください。

test.support.INTERNET_TIMEOUT¶

インターネットへのネットワークリクエストに対する、秒単位のタイムアウトです。

何らかの理由でインターネットへのリクエストがブロックされたときに、テストが長時間待ち続けないよう、十分短いタイムアウトになっています。

通常、INTERNET_TIMEOUT によるタイムアウトでは、テストを失敗させるのではなくスキップしてください。 transient_internet() を参照してください。

デフォルト値は1分です。

LOOPBACK_TIMEOUT も参照してください。

test.support.SHORT_TIMEOUT¶

テストに「時間がかかりすぎる」場合に失敗と判定するための、秒単位のタイムアウトです。

タイムアウトの値は regrtest のコマンドラインオプション --timeout に依存します。

SHORT_TIMEOUT を使うテストが低速な buildbot で不規則に失敗するようになった場合は、代わりに LONG_TIMEOUT を使ってください。

デフォルト値は30秒です。

test.support.LONG_TIMEOUT¶

テストがハングしたことを検出するための、秒単位のタイムアウトです。

最も低速な Python buildbot でもテストが失敗するリスクを減らせるよう、十分な長さになっています。テストに「時間がかかりすぎる」という理由で失敗と判定するために使わないでください。タイムアウトの値は regrtest のコマンドラインオプション --timeout に依存します。

デフォルト値は5分です。

LOOPBACK_TIMEOUT、INTERNET_TIMEOUT、SHORT_TIMEOUT も参照してください。

test.support.PGO¶: テストが PGO (Profile Guided Optimization) の役に立たないときにスキップできるなら設定します。

test.support.PIPE_MAX_SIZE¶: 書き込みをブロックするための、基底にある OS のパイプバッファサイズより大きいであろう定数。

test.support.Py_DEBUG¶: Python が Py_DEBUG マクロを定義してビルドされている場合、つまりデバッグモードでビルドされている場合は True です。

Added in version 3.12.

test.support.SOCK_MAX_SIZE¶: 書き込みをブロックするための、基底にある OS のソケットバッファサイズより大きいであろう定数。

test.support.TEST_SUPPORT_DIR¶: test.support を含む最上位のディレクトリに設定されます。

test.support.TEST_HOME_DIR¶: テストパッケージのトップディレクトリを設定します。

test.support.TEST_DATA_DIR¶: テストパッケージ内の data ディレクトリを設定します。

test.support.MAX_Py_ssize_t¶: 大量のメモリを使うテストのための sys.maxsize を設定します。

test.support.max_memuse¶: 大量のメモリを使うテストのメモリ上限として、set_memlimit() によって設定されます。上限は MAX_Py_ssize_t です。

test.support.real_max_memuse¶: 大量のメモリを使うテストのメモリ上限として、set_memlimit() によって設定されます。 MAX_Py_ssize_t による上限はありません。

test.support.MISSING_C_DOCSTRINGS¶

Python がドキュメンテーション文字列なしでビルドされている場合 (WITH_DOC_STRINGS マクロが定義されていない場合) は True に設定されます。 configure --without-doc-strings オプションを参照してください。

HAVE_DOCSTRINGS 変数も参照してください。

test.support.HAVE_DOCSTRINGS¶

関数のドキュメンテーション文字列を利用できる場合は True に設定されます。 Python で実装された関数のドキュメンテーション文字列を除去する python -OO オプションを参照してください。

MISSING_C_DOCSTRINGS 変数も参照してください。

test.support.TEST_HTTP_URL¶: ネットワークテスト専用の HTTP サーバーの URL を定義します。

test.support.ALWAYS_EQ¶: 何と比較しても等しいオブジェクトです。異なる型同士の比較のテストに使います。

test.support.NEVER_EQ¶: ALWAYS_EQ も含め、何と比較しても等しくないオブジェクトです。異なる型同士の比較のテストに使います。

test.support.LARGEST¶: 自身を除く何と比較しても大きいオブジェクトです。異なる型同士の比較のテストに使います。

test.support.SMALLEST¶: 自身を除く何と比較しても小さいオブジェクトです。異なる型同士の比較のテストに使います。

test.support モジュールは次の関数を定義しています。

test.support.busy_retry(timeout, err_msg=None, /, *, error=True)¶

break でループを停止するまでループ本体を実行します。

timeout 秒が経過すると、error が真の場合は AssertionError を送出し、偽の場合は単にループを停止します。

以下はプログラム例です:

for _ in support.busy_retry(support.SHORT_TIMEOUT):
    if check():
        break

error=False の使用例です。

for _ in support.busy_retry(support.SHORT_TIMEOUT, error=False):
    if check():
        break
else:
    raise RuntimeError('my custom error')

test.support.sleeping_retry(timeout, err_msg=None, /, *, init_delay=0.010, max_delay=1.0, error=True)¶

指数バックオフを適用する待機方法です。

break でループを停止するまでループ本体を実行します。最初の反復を除き、各反復でスリープします。スリープ時間は反復のたびに倍増し、最大 max_delay 秒になります。

引数の使い方については busy_retry() のドキュメントを参照してください。

SHORT_TIMEOUT 秒後に例外を送出する例です。

for _ in support.sleeping_retry(support.SHORT_TIMEOUT):
    if check():
        break

error=False の使用例です。

for _ in support.sleeping_retry(support.SHORT_TIMEOUT, error=False):
    if check():
        break
else:
    raise RuntimeError('my custom error')

test.support.is_resource_enabled(resource)¶: resource が有効で利用可能ならば True を返します。利用可能なリソースのリストは、 test.regrtest がテストを実行している間のみ設定されます。

test.support.get_resource_value(resource)¶: resource に対して (-u resource=value で) 指定された値を返します。 resource が無効であるか、値が指定されていない場合は None を返します。

test.support.python_is_optimized()¶: Python が -O0 も -Og も指定せずにビルドされている場合は True を返します。

test.support.with_pymalloc()¶: Python が pymalloc を有効にしてビルドされており、free-threaded build ではない場合は True を返します。

test.support.requires(resource, msg=None)¶: resource が利用できなければ、 ResourceDenied を送出します。その場合、 msg は ResourceDenied の引数になります。 __name__ が '__main__' である関数にから呼び出された場合には常に True を返します。テストを test.regrtest から実行するときに使われます。

test.support.sortdict(dict)¶: キーでソートした dict の repr() 結果を返します。

test.support.findfile(filename, subdir=None)¶

filename という名前のファイルへのパスを返します。一致するものが見つからなければ、 filename 自体を返します。 filename 自体もファイルへのパスでありえるので、 filename が返っても失敗ではありません。

subdir を設定することで、パスのディレクトリを直接見に行くのではなく、相対パスを使って見付けにいくように指示できます。

test.support.get_pagesize()¶: ページのサイズをバイト単位で取得します。

Added in version 3.12.

test.support.setswitchinterval(interval)¶: sys.setswitchinterval() を使って、指定された interval を設定します。 Android システムでは、ハングを防ぐために最小の間隔を定めています。

test.support.check_impl_detail(**guards)¶

CPython の実装に固有のテストを制限したり、引数で指定した実装でだけテストを実行したりするには、このチェックを使ってください。実行環境に応じて True または False を返します。使用例です。

check_impl_detail()               # CPython のみ (デフォルト)
check_impl_detail(jython=True)    # Jython のみ
check_impl_detail(cpython=False)  # CPython 以外のすべて

test.support.set_memlimit(limit)¶: 大量のメモリを使うテストのために、max_memuse と real_max_memuse の値を設定します。

test.support.record_original_stdout(stdout)¶: stdout の値を保存します。 regrtest が開始した時点の標準出力を保持するための関数です。

test.support.get_original_stdout()¶: record_original_stdout() で設定された元の標準出力を返します。設定されていなければ sys.stdout を返します。

test.support.args_from_interpreter_flags()¶: sys.flags と sys.warnoptions の現在の設定を再現するコマンドライン引数のリストを返します。

test.support.optim_args_from_interpreter_flags()¶: sys.flags の現在の最適化設定を再現するコマンドライン引数のリストを返します。

test.support.captured_stdin()¶

test.support.captured_stdout()¶

test.support.captured_stderr()¶

名前付きストリ－ムを io.StringIO オブジェクトで一時的に置き換えるコンテキストマネージャです。

出力ストリームの使用例:

with captured_stdout() as stdout, captured_stderr() as stderr:
    print("hello")
    print("error", file=sys.stderr)
assert stdout.getvalue() == "hello\n"
assert stderr.getvalue() == "error\n"

入力ストリ－ムの使用例:

with captured_stdin() as stdin:
    stdin.write('hello\n')
    stdin.seek(0)
    # sys.stdin から入力を読み取るテストコードを呼び出す
    captured = input()
self.assertEqual(captured, "hello")

test.support.disable_faulthandler()¶: faulthandler を一時的に無効にするコンテキストマネージャです。

test.support.gc_collect()¶: できる限り多くのオブジェクトを強制的に回収します。ガベージコレクタは適切なタイミングでの解放を保証しないため、この処理が必要です。つまり、__del__ メソッドが予想より遅く呼ばれたり、弱参照が予想より長く生存したりすることがあります。

test.support.disable_gc()¶: 開始時にガベージコレクタを無効にするコンテキストマネージャです。終了時にはガベージコレクタを元の状態に戻します。

test.support.swap_attr(obj, attr, new_val)¶

属性を新しいオブジェクトに置き換えるコンテキストマネージャです。

使い方:

with swap_attr(obj, "attr", 5):
    ...

with ブロックの間だけ obj.attr を 5 に設定し、ブロックの終了時に元の値に戻します。 obj に attr が存在しない場合は作成し、ブロックの終了時に削除します。

"as" 節がある場合は、その代入先に元の値 (存在しない場合は None) を代入します。

test.support.swap_item(obj, attr, new_val)¶

要素を新しいオブジェクトに置き換えるコンテキストマネージャです。

使い方:

with swap_item(obj, "item", 5):
    ...

with ブロックの間だけ obj["item"] を 5 に設定し、ブロックの終了時に元の値に戻します。 obj に item が存在しない場合は作成し、ブロックの終了時に削除します。

"as" 節がある場合は、その代入先に元の値 (存在しない場合は None) を代入します。

test.support.flush_std_streams()¶: sys.stdout、sys.stderr の順に flush() メソッドを呼び出します。標準エラー出力への書き込み前にログの順序を揃えるために使えます。

Added in version 3.11.

test.support.print_warning(msg)¶: sys.__stderr__ に警告を出力します。メッセージは f"Warning -- {msg}" の形式になります。 msg が複数行の場合は、各行の先頭に "Warning -- " を追加します。

Added in version 3.9.

test.support.wait_process(pid, *, exitcode, timeout=None)¶

プロセス pid が終了するまで待ち、終了コードが exitcode であることを確認します。

プロセスの終了コードが exitcode と等しくない場合は AssertionError を送出します。

プロセスが timeout 秒 (デフォルトは SHORT_TIMEOUT) を超えて実行され続けた場合は、プロセスを強制終了して AssertionError を送出します。 Windows ではタイムアウト機能を利用できません。

Added in version 3.9.

test.support.calcobjsize(fmt)¶: 構造体のメンバが fmt で定義される PyObject のサイズを返します。返される値には Python オブジェクトのヘッダのサイズとアラインメントが含まれます。

test.support.calcvobjsize(fmt)¶: 構造体のメンバが fmt で定義される PyVarObject のサイズを返します。返される値には Python オブジェクトのヘッダのサイズとアラインメントが含まれます。

test.support.checksizeof(test, o, size)¶: For testcase test, assert that the sys.getsizeof for o plus the GC header size equals size.

@test.support.anticipate_failure(condition)¶: 条件に応じてテストに @unittest.expectedFailure を付けるデコレータです。このデコレータを使う場合は、関連する課題管理システムの issue を示すコメントも付けてください。

test.support.system_must_validate_cert(f)¶: TLS 証明書の検証に失敗した場合に、装飾したテストをスキップするデコレータです。

@test.support.run_with_locale(catstr, *locales)¶: 別のロケールで関数を実行し、完了したら適切に元の状態に戻すためのデコレータ。 catstr は (例えば "LC_ALL" のような) ロケールカテゴリを文字列で表したものです。渡された locales が順々に試され、一番最初に出てきた妥当なロケールが使われます。

@test.support.run_with_tz(tz)¶: 指定したタイムゾーンで関数を実行し、終了後に元の状態へ正しく戻すデコレータです。

@test.support.requires_freebsd_version(*min_version)¶: FreeBSD でテストを実行するときの最小バージョンを指定するデコレータです。 FreeBSD のバージョンがこれより古い場合は、テストをスキップします。

@test.support.requires_linux_version(*min_version)¶: Linux でテストを実行するときの最小バージョンを指定するデコレータです。 Linux のバージョンがこれより古い場合は、テストをスキップします。

@test.support.requires_mac_version(*min_version)¶: macOS でテストを実行するときの最小バージョンを指定するデコレータです。 macOS のバージョンがこれより古い場合は、テストをスキップします。

@test.support.requires_gil_enabled¶: フリースレッドビルドでテストをスキップするデコレータです。 GIL が無効の場合は、テストをスキップします。

@test.support.requires_IEEE_754¶: IEEE 754 に準拠しないプラットフォームでテストをスキップするデコレータです。

@test.support.requires_zlib¶: zlib が存在しない場合にテストをスキップするデコレータです。

@test.support.requires_gzip¶: gzip が存在しない場合にテストをスキップするデコレータです。

@test.support.requires_bz2¶: bz2 が存在しない場合にテストをスキップするデコレータです。

@test.support.requires_lzma¶: lzma が存在しない場合にテストをスキップするデコレータです。

@test.support.requires_resource(resource)¶: resource が利用できない場合にテストをスキップするデコレータです。

@test.support.requires_docstrings¶: HAVE_DOCSTRINGS が真の場合にだけテストを実行するデコレータです。

@test.support.requires_limited_api¶: Limited C API が利用できる場合にだけテストを実行するデコレータです。

@test.support.cpython_only¶: CPython にだけ適用できるテストのためのデコレータです。

@test.support.impl_detail(msg=None, **guards)¶: guards を渡して check_impl_detail() を呼び出すデコレータです。 False が返された場合は、msg を理由としてテストをスキップします。

@test.support.thread_unsafe(reason=None)¶: テストがスレッドセーフでないことを示すデコレータです。このテストは --parallel-threads を指定して実行しても、常に 1 つのスレッドで実行されます。

@test.support.no_tracing¶: テストの実行中、一時的にトレースを無効にするデコレータです。

@test.support.refcount_test¶: 参照カウントに関わるテストのためのデコレータです。 CPython 以外で実行される場合はテストを実行しません。トレース関数による予期しない参照カウントの変化を防ぐため、テストの実行中はトレース関数の設定を解除します。

@test.support.bigmemtest(size, memuse, dry_run=True)¶

大量のメモリを使うテストのためのデコレータです。

size はテストに要求するサイズです (単位は任意で、テスト側で解釈します)。 memuse はテストで使う単位あたりのバイト数、またはその適切な推定値です。例えば、それぞれ 4 GiB のバイトバッファが 2 つ必要なテストには、@bigmemtest(size=_4G, memuse=2) を付けられます。

通常、size 引数は装飾したテストメソッドに追加の引数として渡されます。 dry_run が True の場合、テストメソッドに渡される値は要求した値より小さくなることがあります。 dry_run が False の場合は、-M が指定されていないときのダミー実行をテストがサポートしないことを意味します。

@test.support.bigaddrspacetest¶: アドレス空間を埋め尽くすテストのためのデコレータです。

test.support.linked_to_musl()¶: インタープリタが musl を使ってコンパイルされたことを示す情報がなければ False を返します。それ以外の場合はバージョンを表す 3 要素のタプルを返し、バージョンが不明なら (0, 0, 0)、判明していれば実際のバージョンになります。 skip デコレータで使うことを想定しています。 emscripten と wasi は musl を使ってコンパイルされたと仮定し、それ以外では platform.libc_ver を調べます。

test.support.check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None)¶: statement のコンパイルを試み、構文エラーをテストします。 testcase はテストに使う unittest のインスタンスです。 errtext は送出された SyntaxError の文字列表現にマッチすべき正規表現です。 lineno が None でなければ、例外の行番号と比較します。 offset が None でなければ、例外のオフセットと比較します。

test.support.open_urlresource(url, *args, **kw)¶: Open url. If open fails, raises TestFailed.

test.support.reap_children()¶: サブプロセスを開始するテストでは、setUp()、tearDown()、または tearDownModule() からこの関数を呼び出してください。余分な子プロセス (ゾンビ) が残ってリソースを消費したり、参照リークの調査を妨げたりすることを防げます。

test.support.get_attribute(obj, name)¶: 属性を取得します。 AttributeError が発生した場合は unittest.SkipTest を送出します。

test.support.catch_unraisable_exception()¶

sys.unraisablehook() を使い、送出できない例外を捕捉するコンテキストマネージャです。

例外の値 (cm.unraisable.exc_value) を保存すると循環参照ができます。コンテキストマネージャの終了時に、この循環参照を明示的に断ち切ります。

オブジェクト (cm.unraisable.object) を保存した際、その値がファイナライズ中のオブジェクトである場合は、そのオブジェクトを復活させる可能性があります。コンテキストマネージャの終了時に、保存したオブジェクトを消去します。

使い方:

with support.catch_unraisable_exception() as cm:
    # 「送出できない例外」を発生させるコード
    ...

    # cm.unraisable を使って送出できない例外を調べる
    ...

# この時点では cm.unraisable 属性は存在しない
# (循環参照を断ち切るため)

Added in version 3.8.

test.support.load_package_tests(pkg_dir, loader, standard_tests, pattern)¶

テストパッケージで使うための、unittest の load_tests プロトコルの汎用実装です。 pkg_dir はパッケージのルートディレクトリです。 loader、standard_tests、pattern は load_tests が受け取る引数です。単純な場合、テストパッケージの __init__.py は次のように書けます。

import os
from test.support import load_package_tests

def load_tests(*args):
    return load_package_tests(os.path.dirname(__file__), *args)

test.support.detect_api_mismatch(ref_api, other_api, *, ignore=())¶

ref_api の属性、関数、メソッドのうち、other_api にないものの集合を返します。ただし、ignore に指定した、このチェックで無視する要素は除外します。

デフォルトでは、'_' で始まる非公開属性を除外しますが、'__' で始まり '__' で終わるすべての特殊メソッドを含めます。

Added in version 3.5.

test.support.patch(test_instance, object_to_patch, attr_name, new_value)¶: object_to_patch.attr_name を new_value で置き換えます。また、object_to_patch の attr_name を元に戻す後始末の処理を test_instance に追加します。 attr_name は object_to_patch の有効な属性でなければなりません。

test.support.run_in_subinterp(code)¶: code をサブインタープリタで実行します。 tracemalloc が有効な場合は unittest.SkipTest を送出します。

@test.support.isolation.runInSubprocess(*, options=(), env=None, timeout=None)¶

装飾したテストを新しいインタープリタのサブプロセスで隔離して実行するデコレータです。テスト実行の他の部分とグローバルな状態やインタープリタの状態を共有しません。テストメソッドにも、TestCase のサブクラス全体にも付けられます。装飾するメソッドは追加の引数を取ってはいけません。サブプロセスでの失敗、エラー、スキップは対応するテストについて報告され、失敗またはスキップした個々の サブテスト は個別に報告されます。失敗やエラーの報告では、サブプロセスでの元のトレースバックが例外の原因として表示されます。

メソッド を装飾した場合は、そのメソッドだけがサブプロセスで実行されます。すべてのフィクスチャ (setUp() / tearDown()、setUpClass() / tearDownClass()、setUpModule() / tearDownModule()) は、親プロセスで通常どおり実行されるほか、サブプロセスでもメソッドの実行前後に実行されます。

When a class is decorated, the whole class runs in a single subprocess, and setUpClass(), tearDownClass(), setUp() and tearDown() run once each in the subprocess and are skipped in the parent process. A failure or skip of setUpClass() in the subprocess is reported for the whole class. setUpModule() cannot be controlled by a class decorator, so it still runs in the parent process too; test it with runningInSubprocess if needed.

サブプロセスは、親のテスト実行で有効にされたリソース (-u)、メモリ上限 (-M)、詳細出力の設定 (-v) を引き継ぎます。そのため、requires_resource()、requires()、bigmemtest() などは両方のプロセスで一貫した動作になります。

options は、サブプロセスの実行に使うインタープリタのコマンドラインオプションのシーケンスです。 env は、引き継いだ環境に追加して設定する環境変数のマッピングです。 env 内の値が None の場合は、その変数の設定を解除します。 -E と -I を指定すると、サブプロセスは PYTHONPATH を含む PYTHON* 環境変数を無視することに注意してください。

timeout はサブプロセスを待つ秒数です。時間内に完了しなかった場合は、テストのエラーとして報告されます。デフォルトではタイムアウトはなく、ハングしたテストの処理はテストランナーのタイムアウトに任されます。

サブプロセスをサポートしないプラットフォームでは、テストをスキップします。

test.support.isolation.runningInSubprocess¶: runInSubprocess() が起動した隔離されたサブプロセスでコードを実行している間は True、それ以外 (親プロセスや通常の隔離されていないテスト実行も含みます) は False です。 setUp()、tearDown()、setUpClass()、tearDownClass()、setUpModule()、tearDownModule() などのフィクスチャは、この値を調べてサブプロセスで実行するコードを選べます。

test.support.check_free_after_iterating(test, iter, cls, args=())¶: 反復後に cls のインスタンスが解放されることを検証します。

test.support.missing_compiler_executable(cmd_names=[])¶: cmd_names に列挙されたコンパイラの実行ファイルが存在するか調べます。 cmd_names が空の場合は、すべてのコンパイラの実行ファイルを調べます。最初に見つかった存在しない実行ファイルを返し、すべて存在する場合は None を返します。

test.support.check__all__(test_case, module, name_of_module=None, extra=(), not_exported=())¶

module の __all__ 変数にすべての公開名が含まれることを検証します。

モジュールの公開名 (API) は、公開名の命名規則に一致するかどうかと、module 内で定義されたかどうかに基づいて自動的に検出されます。

name_of_module 引数には、どのモジュールで定義された API を公開 API として検出するかを、文字列または文字列のタプルで指定できます。例えば、module が公開 API の一部を他のモジュールからインポートしている場合に使います。インポート元は C のバックエンドであることもあります (csv と _csv など)。

extra 引数には、適切な __module__ 属性を持たないオブジェクトなど、自動的には「公開」と検出されない名前の集合を指定できます。指定した名前は、自動検出された名前に追加されます。

not_exported 引数には、名前の形式が公開名を示していても公開 API の一部として扱ってはいけない名前の集合を指定できます。

使用例:

import bar
import foo
import unittest
from test import support

class MiscTestCase(unittest.TestCase):
    def test__all__(self):
        support.check__all__(self, foo)

class OtherTestCase(unittest.TestCase):
    def test__all__(self):
        extra = {'BAR_CONST', 'FOO_CONST'}
        not_exported = {'baz'}  # ドキュメントに記載されていない名前
        # bar は API の一部を _bar からインポートする
        support.check__all__(self, bar, ('bar', '_bar'),
                             extra=extra, not_exported=not_exported)

Added in version 3.6.

test.support.skip_if_broken_multiprocessing_synchronize()¶: multiprocessing.synchronize モジュールが存在しない場合、利用できるセマフォの実装がない場合、またはロックの作成時に OSError が発生する場合は、テストをスキップします。

Added in version 3.10.

test.support.check_disallow_instantiation(test_case, tp, *args, **kwds)¶: args と kwds を使って型 tp のインスタンスを作成できないことを検証します。

Added in version 3.10.

test.support.adjust_int_max_str_digits(max_digits)¶: コンテキストの実行中、グローバルな sys.set_int_max_str_digits() の設定を変更するコンテキストマネージャを返します。整数と文字列の相互変換で、桁数の上限を変更する必要があるテストコードを実行できるようにします。

Added in version 3.11.

test.support モジュールは次のクラスを定義しています。

class test.support.SuppressCrashReport¶

サブプロセスのクラッシュが想定されるテストで、クラッシュを通知するダイアログの表示を抑えようとするコンテキストマネージャです。

Windows では SetErrorMode を使い、Windows エラー報告のダイアログを無効にします。

UNIX では resource.setrlimit() を使って resource.RLIMIT_CORE のソフトリミットを 0 に設定し、コアダンプファイルが作成されることを防ぎます。

どちらのプラットフォームでも、__exit__() で元の値に戻します。

class test.support.SaveSignals¶

Python のシグナルハンドラによって登録されたシグナルハンドラを保存し、復元するクラスです。

save(self)¶: シグナル番号から現在のシグナルハンドラへのマッピングを辞書に保存します。

restore(self)¶: save() が作成した辞書のシグナル番号に、保存したハンドラを設定します。

class test.support.Matcher¶

matches(self, d, **kwargs)¶: 1 つの辞書が指定された引数と一致するか調べます。

match_value(self, k, dv, v)¶: 保存されている 1 つの値 (dv) が、指定された値 (v) と一致するか調べます。

`test.support.socket_helper` --- ソケットのテスト用ユーティリティ¶

test.support.socket_helper モジュールはソケットのテストを支援する機能を提供します。

Added in version 3.9.

test.support.socket_helper.IPV6_ENABLED¶: このホストで IPv6 が有効な場合は True、それ以外の場合は False に設定されます。

test.support.socket_helper.find_unused_port(family=socket.AF_INET, socktype=socket.SOCK_STREAM)¶

Returns an unused port that should be suitable for binding. This is achieved by creating a temporary socket with the same family and type as the sock parameter (default is AF_INET, SOCK_STREAM), and binding it to the specified host address (defaults to 0.0.0.0) with the port set to 0, eliciting an unused ephemeral port from the OS. The temporary socket is then closed and deleted, and the ephemeral port is returned.

テストの実行中、サーバーソケットを特定のポートにバインドする必要があるテストでは、この関数または bind_port() を使ってください。どちらを使うかは、呼び出し側のコードが Python のソケットを作成するのか、それともコンストラクタや外部プログラムに未使用のポートを渡す必要があるのか (例えば openssl の s_server モードの -accept 引数) によって決まります。可能な場合は、常に find_unused_port() より bind_port() を優先してください。ポート番号を固定すると、同じテストを複数同時に実行できなくなることがあり、buildbot で問題になるため、推奨しません。

test.support.socket_helper.bind_port(sock, host=HOST)¶

ソケットを空いているポートにバインドし、ポート番号を返します。エフェメラルポートを使うことで、まだバインドされていないポートであることを保証します。特に buildbot 環境では多くのテストが同時に実行される可能性があるため、これは重要です。 sock.family が AF_INET かつ sock.type が SOCK_STREAM で、ソケットに SO_REUSEADDR または SO_REUSEPORT が設定されている場合は、例外を送出します。テストでは、TCP/IP ソケットにこれらのオプションを設定してはいけません。これらを設定するのは、複数の UDP ソケットでマルチキャストをテストする場合だけです。

さらに、SO_EXCLUSIVEADDRUSE ソケットオプションが利用できる場合 (Windows など) は、これをソケットに設定します。これにより、テストの実行中に他のソケットが同じホストとポートにバインドすることを防ぎます。

test.support.socket_helper.bind_unix_socket(sock, addr)¶: Unix ソケットをバインドします。 PermissionError が発生した場合は unittest.SkipTest を送出します。

@test.support.socket_helper.skip_unless_bind_unix_socket¶: Unix ソケットで bind() が機能することを必要とするテストを実行するためのデコレータです。

test.support.socket_helper.transient_internet(resource_name, *, timeout=30.0, errnos=())¶: インターネット接続のさまざまな問題が例外として発生した場合に、ResourceDenied を送出するコンテキストマネージャです。

`test.support.script_helper` --- Python の実行テスト用ユーティリティ¶

test.support.script_helper モジュールは Python のスクリプト実行テストを支援する機能を提供します。

test.support.script_helper.interpreter_requires_environment()¶

sys.executable が指すインタープリタの実行に環境変数が必要な場合は、True を返します。

assert_python*() 関数を使って隔離モード (-I) または環境変数を無視するモード (-E) で子インタープリタプロセスを起動する必要があるテストに対し、@unittest.skipIf() と組み合わせて使うことを想定しています。

通常のビルドとテストではこの状況にはなりません。ただし、Python の現在のホームディレクトリ検出処理ではホームを特定できないインタープリタから、標準ライブラリのテストスイートを実行しようとすると発生することがあります。

そのような状況でテストスイートの大部分を実行できるようにする方法の 1 つは、PYTHONHOME を設定することです。 PYTHONPATH や PYTHONNOUSERSITE も、インタープリタを起動できるかどうかに影響する可能性がある一般的な環境変数です。

test.support.script_helper.run_python_until_end(*args, **env_vars)¶: サブプロセスでインタープリタを実行するため、env_vars に基づいて環境を設定します。 __isolated、__cleanenv、__cwd、TERM を指定できます。

バージョン 3.9 で変更: stderr から空白を除去しなくなりました。

test.support.script_helper.assert_python_ok(*args, **env_vars)¶

args と省略可能な環境変数 env_vars を使ったインタープリタの実行が成功する (rc == 0) ことを検証し、(return code, stdout, stderr) タプルを返します。

キーワード専用引数 __cleanenv を設定すると、env_vars を新しい環境として使います。

Python is started in isolated mode (command line option -I), except if the __isolated keyword-only parameter is set to False.

バージョン 3.9 で変更: stderr から空白を除去しなくなりました。

test.support.script_helper.assert_python_failure(*args, **env_vars)¶

args と省略可能な環境変数 env_vars を使ったインタープリタの実行が失敗する (rc != 0) ことを検証し、(return code, stdout, stderr) タプルを返します。

その他のオプションについては assert_python_ok() を参照してください。

バージョン 3.9 で変更: stderr から空白を除去しなくなりました。

test.support.script_helper.spawn_python(*args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, **kw)¶

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

kw は subprocess.Popen() に渡す追加のキーワード引数です。 subprocess.Popen オブジェクトを返します。

test.support.script_helper.kill_python(p)¶: 指定された subprocess.Popen のプロセスが完了するまで実行し、標準出力を返します。

test.support.script_helper.make_script(script_dir, script_basename, source, omit_suffix=False)¶: script_dir と script_basename で指定したパスに、source を内容とするスクリプトを作成します。 omit_suffix が False の場合は、名前に .py を追加します。スクリプトの完全なパスを返します。

test.support.script_helper.make_zip_script(zip_dir, zip_basename, script_name, name_in_zip=None)¶: zip_dir と zip_basename で指定した場所に、script_name のファイルを含む、拡張子が zip の zip ファイルを作成します。 name_in_zip はアーカイブ内の名前です。 (完全なパス, アーカイブ内の名前の完全なパス) のタプルを返します。

test.support.script_helper.make_pkg(pkg_dir, init_source='')¶: pkg_dir という名前のディレクトリを作成し、その中に init_source を内容とする __init__ ファイルを作成します。

test.support.script_helper.make_zip_pkg(zip_dir, zip_basename, pkg_name, script_basename, source, depth=1, compiled=False)¶: zip_dir と zip_basename をパスとする zip パッケージディレクトリを作成します。空の __init__ ファイルと、source を内容とする script_basename ファイルを含めます。 compiled が True の場合は、両方のソースファイルをコンパイルして zip パッケージに追加します。 zip の完全なパスと、zip ファイル内のアーカイブ名のタプルを返します。

`test.support.bytecode_helper` --- 正しいバイトコード生成をテストするための支援ツール¶

test.support.bytecode_helper モジュールはバイトコード生成のテストと検査を支援する機能を提供します。

Added in version 3.9.

このモジュールは次のクラスを定義しています。

class test.support.bytecode_helper.BytecodeTestCase(unittest.TestCase)¶: このクラスは、バイトコードを検査するための独自のアサーションメソッドを持ちます。

BytecodeTestCase.get_disassembly_as_string(co)¶: co を逆アセンブルした結果を文字列で返します。

BytecodeTestCase.assertInBytecode(x, opname, argval=_UNSPECIFIED)¶: opname が見つかった場合は命令を返し、それ以外の場合は AssertionError を送出します。

BytecodeTestCase.assertNotInBytecode(x, opname, argval=_UNSPECIFIED)¶: opname が見つかった場合は AssertionError を送出します。

`test.support.threading_helper` --- スレッドのテスト用ユーティリティ¶

test.support.threading_helper モジュールはスレッドのテストを支援する機能を提供します。

Added in version 3.10.

test.support.threading_helper.join_thread(thread, timeout=None)¶: thread を timeout 以内に join します。 timeout 秒後もスレッドが生存している場合は、AssertionError を送出します。

@test.support.threading_helper.reap_threads¶: テストが失敗してもスレッドが確実に後始末されるようにするデコレータです。

test.support.threading_helper.start_threads(threads, unlock=None)¶: スレッドのシーケンス threads を開始するコンテキストマネージャです。 unlock はスレッドの開始後に呼び出す関数で、例外が発生しても呼び出されます。例えば threading.Event.set() を指定できます。 start_threads は終了時に、開始したスレッドを join しようとします。

test.support.threading_helper.threading_cleanup(*original_values)¶: original_values に含まれないスレッドを後始末します。テストがバックグラウンドで動作するスレッドを残した場合に、警告を出すための関数です。

test.support.threading_helper.threading_setup()¶: 現在のスレッド数と、残存するスレッドの集合のコピーを返します。

test.support.threading_helper.wait_threads_exit(timeout=None)¶: with 文内で作成されたすべてのスレッドが終了するまで待つコンテキストマネージャです。

test.support.threading_helper.catch_threading_exception()¶

threading.excepthook() を使って threading.Thread の例外を捕捉するコンテキストマネージャです。

例外を捕捉したときに設定される属性です。

exc_type
exc_value
exc_traceback
thread

threading.excepthook() のドキュメントを参照してください。

これらの属性は、コンテキストマネージャの終了時に削除されます。

使い方:

with threading_helper.catch_threading_exception() as cm:
    # 例外を送出するスレッドを起動するコード
    ...

    # cm の次の属性を使ってスレッドの例外を調べる:
    # exc_type, exc_value, exc_traceback, thread
    ...

# この時点では cm の exc_type, exc_value, exc_traceback, thread 属性は存在しない
# (循環参照を避けるため)

Added in version 3.8.

test.support.threading_helper.run_concurrently(worker_func, nthreads, args=(), kwargs={})¶: ワーカー関数を複数のスレッドで並行して実行します。いずれかのスレッドが例外を送出した場合は、すべてのスレッドの終了後にその例外を再送出します。

`test.support.os_helper` --- os のテスト用ユーティリティ¶

test.support.os_helper モジュールは os のテストを支援する機能を提供します。

Added in version 3.10.

test.support.os_helper.FS_NONASCII¶: os.fsencode() でエンコードできる非 ASCII 文字。

test.support.os_helper.SAVEDCWD¶: os.getcwd() に設定されます。

test.support.os_helper.TESTFN¶: テンポラリファイルの名前として安全に利用できる名前に設定されます。作成した一時ファイルは全て閉じ、unlink (削除) しなければなりません。

test.support.os_helper.TESTFN_NONASCII¶: FS_NONASCII 文字が存在する場合は、その文字を含むファイル名に設定されます。このファイル名が定義されていれば、デフォルトのファイルシステムエンコーディングでエンコードとデコードが可能であることが保証されます。そのため、非 ASCII のファイル名を必要とするテストを、それが動作しないプラットフォームで簡単にスキップできます。

test.support.os_helper.TESTFN_UNENCODABLE¶: strictモードのファイルシステムエンコーディングでエンコードできないファイル名（str型）に設定します。そのようなファイル名を生成できない場合は、 None になる可能性があります。

test.support.os_helper.TESTFN_UNDECODABLE¶: strictモードのファイルシステムエンコーディングでデコードできないファイル名（bytes型）に設定します。そのようなファイル名を生成できない場合は、 None になる可能性があります。

test.support.os_helper.TESTFN_UNICODE¶: 一時ファイル用の非 ASCII の名前に設定されます。

class test.support.os_helper.EnvironmentVarGuard¶: 一時的に環境変数をセット・アンセットするためのクラスです。このクラスのインスタンスはコンテキストマネージャーとして利用されます。また、 os.environ に対する参照・更新を行う完全な辞書のインターフェースを持ちます。コンテキストマネージャーが終了した時、このインスタンス経由で環境変数へ行った全ての変更はロールバックされます。

バージョン 3.1 で変更: 辞書のインターフェースを追加しました。

class test.support.os_helper.FakePath(path)¶: 単純な path-like object です。 path 引数をそのまま返す __fspath__() メソッドを実装しています。 path が例外の場合は、__fspath__() でその例外を送出します。

EnvironmentVarGuard.set(envvar, value)¶: 一時的に、 envvar を value にセットします。

EnvironmentVarGuard.unset(envvar, *others)¶: 1 つ以上の環境変数の設定を一時的に解除します。

バージョン 3.14 で変更: 複数の環境変数の設定を解除できるようになりました。

test.support.os_helper.can_symlink()¶: OS がシンボリックリンクをサポートする場合 True を返し、その他の場合は False を返します。

test.support.os_helper.can_xattr()¶: OS が xattr をサポートする場合は True、それ以外の場合は False を返します。

test.support.os_helper.change_cwd(path, quiet=False)¶

カレントディレクトリを一時的に path に変更し与えるコンテキストマネージャです。

quiet が False の場合、コンテキストマネージャはエラーが起きると例外を送出します。それ以外の場合には、警告を出すだけでカレントディレクトリは同じままにしておきます。

test.support.os_helper.create_empty_file(filename)¶: filename という名前の空のファイルを作成します。すでに存在する場合は、長さを 0 に切り詰めます。

test.support.os_helper.fd_count()¶: 開かれているファイル記述子の数を数えます。

test.support.os_helper.fs_is_case_insensitive(directory)¶: directory のファイルシステムが大文字と小文字を区別しない場合は True を返します。

test.support.os_helper.make_bad_fd()¶: 一時ファイルを開いた後に閉じ、そのファイル記述子を返すことで無効な記述子を作成します。

test.support.os_helper.rmdir(filename)¶: filename に対して os.rmdir() を呼び出します。 Windows では、ファイルの存在を確認する待機ループでこの処理を囲みます。ウイルス対策プログラムがファイルを開いたままにして削除を妨げることがあるため、この処理が必要です。

test.support.os_helper.rmtree(path)¶: path に対して shutil.rmtree() を呼び出すか、os.lstat() と os.rmdir() を使って、パスとその内容を削除します。 rmdir() と同様に、Windows ではファイルの存在を確認する待機ループでこの処理を囲みます。

@test.support.os_helper.skip_unless_symlink¶: シンボリックリンクのサポートが必要なテストを実行することを表すデコレータ。

@test.support.os_helper.skip_unless_xattr¶: xattr のサポートを必要とするテストを実行するためのデコレータです。

test.support.os_helper.temp_cwd(name='tempcwd', quiet=False)¶

一時的に新しいディレクトリを作成し、カレントディレクトリ (current working directory, CWD) を変更するコンテキストマネージャです。

一時的にカレントディレクトリを変更する前に、カレントディレクトリに name という名前のディレクトリを作成します。 name が None の場合は、一時ディレクトリは tempfile.mkdtemp() を使って作成されます。

quiet が False でカレントディレクトリの作成や変更ができない場合、例外を送出します。それ以外の場合には、警告を出すだけで元のカレントディレクトリが使われます。

test.support.os_helper.temp_dir(path=None, quiet=False)¶

path に一時ディレクトリを作成し与えるコンテキストマネージャです。

path が None の場合は、tempfile.mkdtemp() を使って一時ディレクトリを作成します。 quiet が False の場合、コンテキストマネージャはエラー時に例外を送出します。それ以外では、指定された path を作成できなかった場合に警告だけを出します。

test.support.os_helper.temp_umask(umask)¶: 一時的にプロセスの umask を設定するコンテキストマネージャ。

test.support.os_helper.unlink(filename)¶: filename に対して os.unlink() を呼び出します。 rmdir() と同様に、Windows ではファイルの存在を確認する待機ループでこの処理を囲みます。

@test.support.os_helper.with_source_date_epoch(*, epoch=123456789)¶: 環境変数 SOURCE_DATE_EPOCH を epoch に設定してテストを実行するデコレータです。

@test.support.os_helper.without_source_date_epoch¶: 環境変数 SOURCE_DATE_EPOCH の設定を解除してテストを実行するデコレータです。

class test.support.os_helper.SourceDateEpochTestMeta¶

クラスのすべてのテストメソッドをラップするメタクラスです。クラスのキーワード引数 source_date_epoch が真なら with_source_date_epoch()、それ以外なら without_source_date_epoch() でラップします。例えば次のように使います。

class TestsWithSourceEpoch(Tests,
                           metaclass=SourceDateEpochTestMeta,
                           source_date_epoch=True):
    pass

`test.support.import_helper` --- インポートのテスト用ユーティリティ¶

test.support.import_helper モジュールはインポートのテストを支援する機能を提供します。

Added in version 3.10.

test.support.import_helper.forget(module_name)¶: モジュール名 module_name を sys.modules から取り除き、モジュールのバイトコンパイル済みファイルを全て削除します。

test.support.import_helper.import_fresh_module(name, fresh=(), blocked=(), deprecated=False)¶

指定された Python モジュールを、インポート前に sys.modules から削除することで、新しいコピーをインポートして返します。 importlib.reload() とは異なり、元のモジュールはこの操作の影響を受けません。

fresh は、同じようにインポート前に sys.modules から削除されるモジュール名の iterable です。

blocked もモジュール名のイテラブルで、インポート中にモジュールキャッシュ内でその名前を None に置き換えることで、そのモジュールをインポートしようとすると ImportError を発生させます。

指定されたモジュールと fresh や blocked 引数内のモジュール名はインポート前に保存され、フレッシュなインポートが完了したら sys.modules に戻されます。

deprecated が True の場合、インポート中はモジュールとパッケージの廃止メッセージが抑制されます。

指定したモジュールがインポートできなかった場合に、この関数は ImportError を送出します。

使用例:

# テストスイートの他の部分が使うモジュールに影響を与えずにテストできるよう、
# warnings モジュールのコピーを取得する。
# 一方は C の実装を使い、もう一方はフォールバック用の純 Python 実装を
# 強制的に使う
py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
c_warnings = import_fresh_module('warnings', fresh=['_warnings'])

Added in version 3.1.

test.support.import_helper.import_module(name, deprecated=False, *, required_on=())¶

この関数は name で指定されたモジュールをインポートして返します。通常のインポートと異なり、この関数はモジュールをインポートできなかった場合に unittest.SkipTest 例外を発生させます。

deprecated が True の場合、このインポート中はモジュールやパッケージの非推奨メッセージを抑制します。あるプラットフォームでは必須で、他では省略可能なモジュールの場合は、required_on にプラットフォーム名の接頭辞のイテラブルを指定してください。これらは sys.platform と比較されます。

Added in version 3.1.

test.support.import_helper.modules_setup()¶: sys.modules のコピーを返します。

test.support.import_helper.modules_cleanup(oldmodules)¶: 内部キャッシュを保持するために、oldmodules と encodings 以外のモジュールを削除します。

test.support.import_helper.unload(name)¶: sys.modules から name を削除します。

test.support.import_helper.make_legacy_pyc(source)¶: PEP 3147/PEP 488 形式の pyc ファイルを従来の pyc ファイルの場所に移動し、移動先のファイルシステム上のパスを返します。 source はソースファイルのファイルシステム上のパスです。ソースファイルは存在しなくてもかまいませんが、PEP 3147/488 形式の pyc ファイルは存在しなければなりません。

class test.support.import_helper.CleanImport(*module_names)¶

インポートで新しいモジュールの参照を返すように強制するコンテキストマネージャです。インポート時の DeprecationWarning の発生など、モジュールレベルの動作のテストに便利です。使用例です。

with CleanImport('foo'):
    importlib.import_module('foo')  # 新しい参照

class test.support.import_helper.DirsOnSysPath(*paths)¶

sys.path にディレクトリを一時的に追加するコンテキストマネージャです。

sys.path のコピーを作成し、位置引数で指定したディレクトリを末尾に追加します。コンテキストの終了時に、sys.path をコピーした設定に戻します。

コンテキストマネージャの本体で行った sys.path への すべての 変更は、オブジェクトの置き換えも含めて、ブロックの終了時に元に戻ることに注意してください。

`test.support.warnings_helper` --- 警告のテスト用ユーティリティ¶

test.support.warnings_helper モジュールは警告のテストを支援する機能を提供します。

Added in version 3.10.

test.support.warnings_helper.ignore_warnings(*, category)¶

category のインスタンスである警告を抑制します。 category は Warning またはそのサブクラスでなければなりません。 warnings.catch_warnings() と warnings.simplefilter('ignore', category=category) を組み合わせるのとおおむね同等です。例えば次のように使います。

@warning_helper.ignore_warnings(category=DeprecationWarning)
def test_suppress_warning():
    # 何らかの処理を行う

Added in version 3.8.

test.support.warnings_helper.check_no_resource_warning(testcase)¶: ResourceWarning が発生しなかったことを確認するコンテキストマネージャです。 ResourceWarning を発生させる可能性があるオブジェクトは、コンテキストマネージャの終了前に除去しなければなりません。

test.support.warnings_helper.check_syntax_warning(testcase, statement, errtext='', *, lineno=1, offset=None)¶: statement のコンパイルを試み、構文警告をテストします。 SyntaxWarning が一度だけ発生することと、警告をエラーとして扱う設定では SyntaxError になることもテストします。 testcase はテストに使う unittest のインスタンスです。 errtext は、発生した SyntaxWarning と送出された SyntaxError の文字列表現にマッチすべき正規表現です。 lineno が None でなければ、警告と例外の行番号と比較します。 offset が None でなければ、例外のオフセットと比較します。

Added in version 3.8.

test.support.warnings_helper.check_warnings(*filters, quiet=True)¶

警告が正しく発生したことを簡単にテストできるようにする、warnings.catch_warnings() の便利なラッパーです。 warnings.simplefilter() を always に設定して warnings.catch_warnings(record=True) を呼び出すのとほぼ同等で、記録した結果を自動的に検証するオプションもあります。

check_warnings は ("message regexp", WarningCategory) の形をした 2要素タプルを位置引数として受け取ります。1つ以上の filters が与えられた場合や、オプションのキーワード引数 quiet が False の場合、警告が期待通りであるかどうかをチェックします。指定された各 filter は最低でも1回は囲われたコード内で発生した警告とマッチしなければテストが失敗しますし、指定されたどの filter ともマッチしない警告が発生してもテストが失敗します。前者のチェックを無効にするには、quiet を True にします。

引数が1つもない場合、デフォルトでは次のようになります:

check_warnings(("", Warning), quiet=True)

この場合、すべての警告が捕捉され、エラーは発生しません。

コンテキストマネージャの開始時に、WarningsRecorder インスタンスが返されます。記録した警告は warnings 属性から利用でき、reset() メソッドはそれまでに記録した警告を破棄します。

コンテキストマネージャーは次のようにして使います:

with check_warnings(("assertion is always true", SyntaxWarning),
                    ("", UserWarning)):
    exec('assert(False, "Hey!")')
    warnings.warn(UserWarning("Hide me!"))

この場合、いずれかの警告が発生しなかった場合や、それ以外の警告が発生した場合は、 check_warnings() はエラーを発生させます。

警告が発生したかどうかだけでなく、もっと詳しいチェックが必要な場合は、次のようなコードになります:

with check_warnings(quiet=True) as w:
    warnings.warn("foo")
    assert str(w.message) == "foo"
    warnings.warn("bar")
    assert str(w.message) == "bar"
    assert str(w.warnings[0].message) == "foo"
    assert str(w.warnings[1].message) == "bar"
    w.reset()
    assert len(w.warnings) == 0

全ての警告をキャプチャし、テストコードがその警告を直接テストします。

バージョン 3.2 で変更: 新しいオプション引数 filters と quiet

class test.support.warnings_helper.WarningsRecorder(warnings_list)¶

単体テスト用に警告を記録するクラスです。記録を有効にした warnings.catch_warnings() が返す警告のリストをラップします。 check_warnings() はこのクラスのインスタンスを返します。

利便性のため、最新の警告を表すオブジェクトの属性には、記録用のオブジェクトからも直接アクセスできます。記録用のオブジェクトを作成した後、または最後にリセットした後に警告が発生していなければ、これらの属性は None を返します。

warnings¶: 記録用のオブジェクトを作成した後、または最後にリセットした後に記録された警告のリストです。

reset()¶: それまでに記録した警告を、記録用のオブジェクトから見えなくします。元の警告のリストは変更しません。

`test` --- Python の回帰テストパッケージ¶

`test` パッケージの単体テストを書く¶

コマンドラインインターフェースを利用してテストを実行する¶

`test.support` --- Python テストスイート用のユーティリティ¶

`test.support.socket_helper` --- ソケットのテスト用ユーティリティ¶

`test.support.script_helper` --- Python の実行テスト用ユーティリティ¶

`test.support.bytecode_helper` --- 正しいバイトコード生成をテストするための支援ツール¶

`test.support.threading_helper` --- スレッドのテスト用ユーティリティ¶

`test.support.os_helper` --- os のテスト用ユーティリティ¶

`test.support.import_helper` --- インポートのテスト用ユーティリティ¶

`test.support.warnings_helper` --- 警告のテスト用ユーティリティ¶

目次

前のトピックへ

次のトピックへ

このページ

test --- Python の回帰テストパッケージ¶

test パッケージの単体テストを書く¶

コマンドラインインターフェースを利用してテストを実行する¶

test.support --- Python テストスイート用のユーティリティ¶

test.support.socket_helper --- ソケットのテスト用ユーティリティ¶

test.support.script_helper --- Python の実行テスト用ユーティリティ¶

test.support.bytecode_helper --- 正しいバイトコード生成をテストするための支援ツール¶

test.support.threading_helper --- スレッドのテスト用ユーティリティ¶

test.support.os_helper --- os のテスト用ユーティリティ¶

test.support.import_helper --- インポートのテスト用ユーティリティ¶

test.support.warnings_helper --- 警告のテスト用ユーティリティ¶

`test` --- Python の回帰テストパッケージ¶

`test` パッケージの単体テストを書く¶

`test.support` --- Python テストスイート用のユーティリティ¶

`test.support.socket_helper` --- ソケットのテスト用ユーティリティ¶

`test.support.script_helper` --- Python の実行テスト用ユーティリティ¶

`test.support.bytecode_helper` --- 正しいバイトコード生成をテストするための支援ツール¶

`test.support.threading_helper` --- スレッドのテスト用ユーティリティ¶

`test.support.os_helper` --- os のテスト用ユーティリティ¶

`test.support.import_helper` --- インポートのテスト用ユーティリティ¶

`test.support.warnings_helper` --- 警告のテスト用ユーティリティ¶