###
5 DocTestRunner オブジェクト

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

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

  予想出力と実際の出力との比較は `OutputChecker` で行います。 比較は様々なオプションフラグを使ってカスタマイズできます; 詳しくは23.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 を使うと、テストランナが 予想出力と実際の出力を比較する方法や、テストの失敗を表示する方法を 制御できます。詳しくは23.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` 自体の冗長度を使います。