##
8 単位テスト API

doctest 化したモジュールのコレクションが増えるにつれ、全ての doctest を システマティックに実行したいと思うようになるはずです。 Python 2.4 以前の `doctest` には `Tester` という ほとんどドキュメント化されていないクラスがあり、複数のモジュールの doctest を統合する初歩的な手段を提供していました。 `Tester` は非力であり、実際のところ、もっときちんとした Python の テストフレームワークが `unittest` モジュールで構築されており、 複数のソースコードからのテストを統合する柔軟な方法を提供しています。 そこで Python 2.4 では `doctest` の `Tester` クラスを 撤廃し、モジュールや doctest の入ったテキストファイルから `unittest` テストスイートを作成できるような二つの関数を `doctest` 側で提供するようにしました。 こうしたテストスイートは、`unittest` のテストランナを 使って実行できます:

    import unittest
    import doctest
    import my_module_with_doctests, and_another

    suite = unittest.TestSuite()
    for mod in my_module_with_doctests, and_another:
        suite.addTest(doctest.DocTestSuite(mod))
    runner = unittest.TextTestRunner()
    runner.run(suite)

doctest の入ったテキストファイルやモジュールから ``unittest`.TestSuite` インスタンスを生成するための 主な関数は二つあります:

`DocFileSuite`( | [module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding])

  単一または複数のテキストファイルに入っている doctest 形式のテストを、 ``unittest`.TestSuite` インスタンスに変換します。

  この関数の返す``unittest`.TestSuite` インスタンスは、 unittest フレームワークで動作させ、各ファイルの例題を対話的に実行する ためのものです。ファイル内の何らかの例題の実行に失敗すると、この関数で 生成した単位テストは失敗し、該当するテストの入っているファイルの名前と、 (場合によりだいたいの) 行番号の入った`failureException` 例外を 送出します。

  関数には、テストを行いたい一つまたは複数のファイルへのパスを (文字列で) 渡します。

  `DocFileSuite` には、キーワード引数でオプションを指定できます:

  オプション引数module_relative はpaths に指定したファイル名を どのように解釈するかを指定します:

  - module_relative が `True` (デフォルト) の場合、 filename は OS に依存しないモジュールの相対パスになります。 デフォルトでは、このパスは関数 `testfile` を呼び出して いるモジュールからの相対パスになります; ただし、package 引数を指定した場合には、パッケージからの相対になります。 OS への依存性を除くため、filename ではパスを分割する 文字に`/` を使わねばならず、絶対パスにしてはなりません (パス文字列を`/` で始めてはなりません)。
  - module_relative が `False` の場合、filename は OS 依存のパスを示します。パスは絶対パスでも相対パスでも かまいません; 相対パスにした場合、現在の作業ディレクトリを 基準に解決します。

  オプション引数 package には、 Python パッケージを指定するか、 モジュール相対のファイル名の場合には相対の基準ディレクトリとなる Python パッケージの名前を指定します。パッケージを指定しない倍、 関数を呼び出しているモジュールのディレクトリを相対の基準 ディレクトリとして使います。module_relative を`False` に指定している場合、package を指定するとエラーになります。

  オプション引数 setUp には、テストスイートのセットアップに使う 関数を指定します。この関数は、各ファイルのテストを実行する前に 呼び出されます。 setUp 関数は `DocTest` オブジェクトに 引き渡されます。setUp はglobs 属性を介してテストの グローバル変数にアクセスできます。

  オプション引数 tearDown には、テストを解体 (tear-down) する ための関数を指定します。この関数は、各ファイルのテストの実行を 終了するたびに呼び出されます。tearDown関数は `DocTest` オブジェクトに引き渡されます。tearDown ははglobs 属性を 介してテストのグローバル変数にアクセスできます。

  オプション引数 globs は辞書で、テストのグローバル変数 の初期値が入ります。この辞書は各テストごとに新たにコピーして使われ ます。デフォルトでは globs は空の新たな辞書です。

  オプション引数 optionflags には、テストを実行する際に デフォルトで適用される doctest オプションを OR で結合して 指定します。 23.2.6 節を参照してください。 結果レポートに関するオプションの指定する上手いやり方は 下記の`set_unittest_reportflags()` の説明を参照してください。

  オプション引数 parser には、ファイルからテストを抽出するために 使う`DocTestParser` (またはサブクラス) を指定します。 デフォルトは通常のパーザ (``DocTestParser`()`) です。

  オプション引数 encoding にはファイルをユニコードに変換する際に使われる エンコーディングを指定します。

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

  バージョン 2.5 で 変更 された仕様: グローバル変数 `__file__` が追加され `DocFileSuite()` を使ってテキストファイルから読み込まれた doctest に提供されます

  バージョン 2.5 で 変更 された仕様: encoding パラメタが追加されました

`DocTestSuite`( | [module][, globs][, extraglobs][, test_finder][, setUp][, tearDown][, checker])

  doctest のテストを ``unittest`.TestSuite` に変換します。

  この関数の返す``unittest`.TestSuite` インスタンスは、 unittest フレームワークで動作させ、モジュール内の各 doctest を実行する ためのものです。何らかの doctest の実行に失敗すると、この関数で 生成した単位テストは失敗し、該当するテストの入っているファイルの名前と、 (場合によりだいたいの) 行番号の入った`failureException` 例外を 送出します。

  オプション引数 module には、テストしたいモジュールの名前を 指定します。module にはモジュールオブジェクトまたは (ドット表記の) モジュール名を指定できます。module を指定しない場合、この関数を 呼び出しているモジュールになります。

  オプション引数 globs は辞書で、テストのグローバル変数 の初期値が入ります。この辞書は各テストごとに新たにコピーして使われ ます。デフォルトではglob は空の新たな辞書です。

  オプション引数 extraglobs には追加のグローバル変数セットを 指定します。この変数セットは globs に統合されます。 デフォルトでは、追加のグローバル変数はありません。

  オプション引数 test_finder は、モジュールから doctest を抽出 するための `DocTestFinder` オブジェクト (またはその代用となる オブジェクト) です。

  オプション引数 setUp、tearDown、および optionflags は上の `DocFileSuite()` と同じです。

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

  バージョン 2.4 で 変更 された仕様: globs, extraglobs, test_finder, setUp, tearDown, および optionflags パラメタを追加しました。また、この関数は doctest の検索に`testmod()` と同じテクニックを使うように なりました

`DocTestSuite()` は水面下では`doctest.DocTestCase` インスタンスから``unittest`.TestSuite` を作成しており、 `DocTestCase` は``unittest`.TestCase` のサブクラス になっています。`DocTestCase` についてはここでは説明しません (これは内部実装上の詳細だからです) が、そのコードを調べてみれば、 `unittest` の組み込みの詳細に関する疑問を解決できるはずです。

同様に、`DocFileSuite()` は`doctest.DocFileCase` インスタンスから``unittest`.TestSuite` を 作成し、 `DocFileCase` は `DocTestCase` のサブクラス になっています。これにははっきりとした訳があります: `doctest` 関数を自分で実行する場合、オプションフラグを `doctest` 関数に渡すことで、`doctest` のオプションを直接操作できます。しかしながら、`unittest` フレームワークを書いている場合には、いつどのようにテストを動作させるかを `unittest` が完全に制御してしまいます。フレームワークの作者は たいてい、`doctest` のレポートオプションを (コマンドライン オプションで指定するなどして) 操作したいと考えますが、`unittest` を介して `doctest` のテストランナにオプションを渡す方法は 存在しないのです。

このため、`doctest` では、以下の関数を使って、 `unittest` サポート に特化したレポートフラグ表記方法もサポートしています:

`set_unittest_reportflags`( | flags)

  `doctest` のレポートフラグをセットします。

  引数flags にはオプションフラグを OR で結合して渡します。 23.2.6 節を参照してください。「レポートフラグ」 しか使えません。

  この関数で設定した内容はモジュール全体にわたる物であり、関数呼び出し 以後に `unittest` モジュールから実行される全ての doctest に影響します: `DocTestCase` の`runTest()` メソッド は、`DocTestCase` インスタンスが作成された際に、現在の テストケースに指定されたオプションフラグを見に行きます。 レポートフラグが指定されていない場合 (通常の場合で、望ましいケースです)、 `doctest` の `unittest` レポートフラグが OR で 結合され、doctest を実行するために作成される`DocTestRunner` インスタンスに渡されます。 `DocTestCase` インスタンスを構築する際に何らかのレポートフラグが 指定されていた場合、`doctest` の`unittest` レポートフラグは無視されます。

  この関数は、関数を呼び出す前に有効になっていた`unittest` レポートフラグの値を返します。

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