## 12 進んだ使い方

doctest をどのように動作させるかを制御する、いくつかのモジュール レベルの関数が利用できます。

`debug`( | module, name)

  doctest を含む単一のドキュメンテーション文字列をデバッグします。

  デバッグしたいドキュメンテーション文字列の入った module (またはドットで区切ったモジュール名) と、(モジュール内の) デバッグしたいドキュメンテーション文字列を持つオブジェクトの name を指定してください。

  doctest の例が展開され (`testsource()` 関数を参照してください)、 一次ファイルに書き込まれます。次に Python デバッガ `pdb` がこのファイルに対して起動されます。 バージョン 2.3 で 新たに追加 された仕様です。

`testmod`( | )

  この関数は doctest への基本的なインタフェース提供します。 この関数は `Tester` のローカルなインスタンスを生成し、 このクラスの適切なメソッドを動作させ、結果をグローバルな `Tester` インスタンスである `master` に統合します。

  `testmod()` が提供するよりも細かい制御を行うには、 `Tester` のインスタンスを自作のポリシで作成するか、 `master` のメソッドを直接呼び出します。詳細は `Tester.__doc__` を参照してください。

`testsource`( | module, name)

  doctest の例をドキュメンテーション文字列から展開します。

  展開したいテストの入った module (またはドットで区切られた モジュールの名前) と、展開したいテストの入った docstring を 持つオブジェクトの (モジュール内の) name を与えます。

  doctest 内の例は Python コードの入った文字列として返されます。 例中での予想される出力のブロックは Python のコメントに変換 されます。 バージョン 2.3 で 新たに追加 された仕様です。

`DocTestSuite`( | [module])

  モジュールにおける doctest のテストプログラムを ``unittest`.TestSuite` に変換します。

  返される `TestSuite` は unittest フレームワークで動作する ためのもので、モジュール内の各 doctest を走らせます。 doctest のいずれかが失敗すると、生成された unittest が失敗し、 該当するテストを含むファイルと (時に近似の) 行番号を表示する `DocTestTestFailure` 例外が送出されます。

  オプションの module 引数はテストするモジュールを与えます。 この値はモジュールオブジェクトか (場合によってはドットで区切られた) モジュール名となります。指定されていなければ、この関数を呼び出している モジュールが使われます。

  `unittest` モジュールが `TestSuite` を 利用する数多くの方法のうちの一つを使った例を以下に示します:

          import unittest
          import doctest
          import my_module_with_doctests

          suite = doctest.DocTestSuite(my_module_with_doctests)
          runner = unittest.TextTestRunner()
          runner.run(suite)

  バージョン 2.3 で 新たに追加 された仕様です。 警告: この関数は現在のところ `M.__test__` を検索せず、 その検索テクニックはあらゆる点で `testmod()` と合致しません。 将来のバージョンではこれら二つを収斂させる予定です。