5.2.9.5 DocTestRunner オブジェクト

クラス DocTestRunner( [checker][, verbose][, optionflags])

DocTest 内の対話モード例題を実行し、検証する際に用いられる処理クラスです。

予想出力と実際の出力との比較は OutputChecker で行います。比較は様々なオプションフラグを使ってカスタマイズできます; 詳しくは5.2.6 を参照してください。オプションフラグでは不十分な場合、コンストラクタに OutputChecker のサブクラスを渡して比較方法をカスタマイズできます。

テストランナの表示出力の制御には二つの方法があります。一つ目は、TestRunner.run() に出力用の関数を渡すというものです。この関数は、表示すべき文字列を引数にして呼び出されます。デフォルトは sys.stdout.write です。出力を取り込んで処理するだけでは不十分な場合、DocTestRunner をサブクラス化し、 report_start, report_success, report_unexpected_exception, および report_failure をオーバライドすればカスタマイズできます。

オプションのキーワード引数checker には、OutputChecker オブジェクト (またはその代用品) を指定します。このオブジェクトは doctest 例題の予想出力と実際の出力との比較を行う際に使われます。

オプションのキーワード引数verbose は、DocTestRunner の出すメッセージの冗長性を制御します。verbose がTrue の場合、各例題を実行するつど、その例題についての情報を出力します。 verbose がFalse の場合、テストの失敗だけを出力します。 verbose を指定しない場合やNone を指定した場合、コマンドラインスイッチ -v を使った場合にのみ verbose 出力を適用します。

オプションのキーワード引数optionflags を使うと、テストランナが予想出力と実際の出力を比較する方法や、テストの失敗を表示する方法を制御できます。詳しくは5.2.6 節を参照してください。

バージョン 2.4 で新たに追加された仕様です。

DocTestRunner では、以下のメソッドを定義しています:

report_start( out, test, example): テストランナが例題を処理しようとしているときにレポートを出力します。 DocTestRunner の出力をサブクラスでカスタマイズできるようにするためのメソッドです。直接呼び出してはなりません。
example は処理する例題です。test は example の入っているテストです。out は出力用の関数で、 DocTestRunner.run() に渡されます。

report_success( out, test, example, got): 与えられた例題が正しく動作したことを報告します。このメソッドは DocTestRunner のサブクラスで出力をカスタマイズできるようにするために提供されています; 直接呼び出してはなりません。
example は処理する例題です。got は例題から実際に得られた出力です。test は example の入っているテストです。 out は出力用の関数で、DocTestRunner.run() に渡されます。

report_failure( out, test, example, got): 与えられた例題が正しく動作しなかったことを報告します。このメソッドは DocTestRunner のサブクラスで出力をカスタマイズできるようにするために提供されています; 直接呼び出してはなりません。
example は処理する例題です。got は例題から実際に得られた出力です。test は example の入っているテストです。 out は出力用の関数で、DocTestRunner.run() に渡されます。

report_unexpected_exception( out, test, example, exc_info): 与えられた例題が予想とは違う例外を送出したことを報告します。このメソッドは DocTestRunner のサブクラスで出力をカスタマイズできるようにするために提供されています; 直接呼び出してはなりません。
example は処理する例題です。exc_info には予期せず送出された例外の情報を入れたタプル (sys.exc_info() の返す内容) になります。test は example の入っているテストです。 out は出力用の関数で、DocTestRunner.run() に渡されます。

run( test[, compileflags][, out][, clear_globs])

test 内の例題 (DocTest オブジェクト) を実行し、その結果を出力用の関数out を使って表示します。

例題は名前空間 test.globs の下で実行されます。 clear_globs が真 (デフォルト) の場合、名前空間はテストの実行後に消去され、ガベージコレクションをうながします。テストの実行完了後にその内容を調べたければ、clear_globs を False にしてください。

compileflags には、例題を実行する際に Python コンパイラに適用するフラグセットを指定します。compileflags を指定しない場合、デフォルト値はglobs で適用されている future-import フラグセットになります。

各例題の出力は DocTestRunner の出力チェッカで検査され、その結果は DocTestRunner.report_*. メソッドで書式化されます。

summarize( [verbose]): この DocTestRunner が実行した全てのテストケースのサマリを出力し、タプル"(failure_count, test_count)" を返します。
オプションのverbose 引数を使うと、どのくらいサマリを詳しくするかを制御できます。冗長度を指定しない場合、DocTestRunner 自体の冗長度を使います。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。