pygame.tests.run - Pygameの単体テストスイートを実行します。

コマンドラインから素早くテストスイートパッケージを実行するには、Python <pygameのインストールされているフォルダパス>.tests [option]を使用してサブモジュールの読み込みを行います。

  python <pygameのインストールされているフォルダパス>.tests [<test options>]

コマンドラインオプション -「python -help」を実行すると詳細な使用方法が表示されます。オプションには pygame.tests.run の項目で説明している引数と同じものが設定できます。

テストパッケージの中には xxxx_test という名前のサブモジュールが含まれており、それらは Pygame の各機能の単体テストに使うスイートです。サブモジュールはメインプログラムとして単体で実行することもできます。 cdrom_test のようにユーザーの入力操作が必要なテストの場合は、単体で実行するほうが良いでしょう。

Pygame 開発に使うテストスイートは、 Pygame がインストールされているルートディレクトリで実行することができます。 python tests コマンドを実行して直接テストすることもできますが、より簡単にテストをするために run_tests.py モジュールが用意されています。

モジュールレベルタグによって、単体テスト実行時に読み込むモジュールを調節します。 <name>_tags.py モジュールに記載されたタグレベルが、 <name>_tags.py の単体テストに適用されます。タグモジュール内のグローバル定義 __tags__ に、タグレベルの一覧が記載されています。例えば、 cdrom_test.py には cdrom_tags.py というタグファイルが付属しており、その中に適用されるタグの一覧が記載されています。 cdrom_tags.py の場合は 'interactive' と記載されています。 cdrom_test.py のテストにはユーザーからの入力処理が必要のため、 'interactive' レベルのタグが適用されています。このタグが適用されていると、run_tests.py や python tests コマンドを実行した際の自動テストでは除外されます。他にも 'ignore' と 'subprocess_ignore' の二つのタグがあります。単体テストが実行できない環境だったり、対応する Pygame モジュールが使用できない場合はこれら二つのタグが自動で適用されます。テスト実行時には、除外されたテストモジュールとそのタグレベルが一覧表示されます。

※原文のコマンドではテストが実行できなかったため、独自に動作確認した -m オプションを除くコマンドを記載しています。

Pygameの単体テストスイートを実行します。
pygame.tests.run(*args, **kwds): return tuple


固定引数 (optional):

    読み込むテストモジュールの名前を引数として設定します。引数が設定されていない場合は、全てのテストモジュールが実行されます。
    設定するテストモジュール名には、末尾の'_test'まで含める必要はありません。

キーワード引数:

    incomplete   - fail incomplete tests (既定ではFalseが設定されています)
    
    nosubprocess - 全てのテストスイートを現在動いているプロセス上で実行します。
                   (既定ではFalseが設定されており、テストスイートは個々のサブプロセス上で実行されます)
                   
    dump         - テスト結果の failure 情報と error 情報をdict型の値として出力します。(既定ではFalseが設定されています)
    
    file         - 設定された値は、 failure 情報と error 情報が出力されるファイルの名前になります。
    
    timings      - 設定された値は、各テストの実行回数となります。テストでは平均処理時間が取得されます。
                   (既定では各テストは1回ずつ実行されます)
                   
    exclude      - 実行時に除外するタグレベルの一覧を設定します。
    
    show_output  - show silenced stderr/stdout on errors (既定ではFalseが設定されています)
    
    all          - エラーだけでなく、全ての実行結果を出力します。(既定ではFalseが設定されています)
    
    randomize    - テストの実行順番をランダムにします。(既定ではFalseが設定されています)
    
    seed         - 設定された場合、ランダム値が生成されます
    
    multi_thread - 設定した値は、サブプロセスでテストを実行する際のスレッド数となります。
    
    time_out     - サブプロセスが有効になっている場合、テストを強制終了するまでの制限時間を秒単位で設定します。
                   既定では30が設定されています)
                   
    fake         - 実行するフェイクテスト名を設定します。通常の pygame.tests モジュールのテストではなく
                   引数に設定された pygame.tests.run_tests__tests モジュールのフェイクテストを実行します。
                   
    python       - サブプロセスモードのテストを実行するための、 python の実行パス
                   (既定ではsys.executableが設定されています)

戻り値:

    実行したテストの数とエラー情報が記録されたdict値の2つが、タプル型の値として取得されます。
    エラーが発生しなかった場合は、dict値は空になります。

既定では、個々のテストモジュールはサブプロセスに分けられて実行されます。これによって、プログラムの実行時にはpygame.init と pygame.quitはそれぞれ一度だけ実行される、という通常のPygameの動作を再現でき、テストモジュール同士の予期せぬ干渉を防ぎます。また、テストには制限時間が設けられているため、フリーズテストを行っていても制限時間が来ると強制的に終了されてしまいます。スレッドが正常に動作しなかったり、テストに時間がかかりすぎる場合にはシングルプロセスオプションで実行してください。ただし、全てのテストでシンプルプロセスモードで正常に動作するとは限りません。

randomize引数にTrueが設定されるかseed引数が設定されていた場合は、テストはランダムな順番で実行されます。seed引数が設定されていない場合は、システム時刻がランダム値として使用されます。

各テストモジュールには__tags__属性が設定されており、それによってテスト実行時に除外するモジュールが選別されます。既定では、cdrom_testのように'interactive'タグが設定されたモジュールのみが除外されます。'interactive'タグの設定されたモジュールは単体のPygameプログラムとして実行しなければなりません。

この命令は、Pythonのプログラム動作中に1回だけ実行することができます。2回以上実行することはできません。




Run the Pygame unit test suite. pygame.tests.run(*args, **kwds): return tuple Positional arguments (optional): The names of tests to include. If omitted then all tests are run. Test names need not include the trailing '_test'. Keyword arguments: incomplete - fail incomplete tests (default False) nosubprocess - run all test suites in the current process (default False, use separate subprocesses) dump - dump failures/errors as dict ready to eval (default False) file - if provided, the name of a file into which to dump failures/errors timings - if provided, the number of times to run each individual test to get an average run time (default is run each test once) exclude - A list of TAG names to exclude from the run show_output - show silenced stderr/stdout on errors (default False) all - dump all results, not just errors (default False) randomize - randomize order of tests (default False) seed - if provided, a seed randomizer integer multi_thread - if provided, the number of THREADS in which to run subprocessed tests time_out - if subprocess is True then the time limit in seconds before killing a test (default 30) fake - if provided, the name of the fake tests package in the run_tests__tests subpackage to run instead of the normal Pygame tests python - the path to a python executable to run subprocessed tests (default sys.executable) Return value: A tuple of total number of tests run, dictionary of error information. The dictionary is empty if no errors were recorded. By default individual test modules are run in separate subprocesses. This recreates normal Pygame usage where pygame.init - initialize all imported pygame modules and pygame.quit - uninitialize all pygame modules are called only once per program execution, and avoids unfortunate interactions between test modules. Also, a time limit is placed on test execution, so frozen tests are killed when there time allotment expired. Use the single process option if threading is not working properly or if tests are taking too long. It is not guaranteed that all tests will pass in single process mode. Tests are run in a randomized order if the randomize argument is True or a seed argument is provided. If no seed integer is provided then the system time is used. Individual test modules may have a __tags__ attribute, a list of tag strings used to selectively omit modules from a run. By default only 'interactive' modules such as cdrom_test are ignored. An interactive module must be run from the console as a Python program. This function can only be called once per Python session. It is not reentrant.