 |
 |
 |
Python ライブラリリファレンス |  |
 |
 |
|
|
|
Python ライブラリリファレンス | |
|
|
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 インスタンスを生成するための 主な関数は二つあります:
| [module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding]) |
単一または複数のテキストファイルに入っている doctest 形式のテストを、 unittest.TestSuite インスタンスに変換します。
この関数の返すunittest.TestSuite インスタンスは、 unittest フレームワークで動作させ、各ファイルの例題を対話的に実行する ためのものです。ファイル内の何らかの例題の実行に失敗すると、この関数で 生成した単位テストは失敗し、該当するテストの入っているファイルの名前と、 (場合によりだいたいの) 行番号の入ったfailureException 例外を 送出します。
関数には、テストを行いたい一つまたは複数のファイルへのパスを (文字列で) 渡します。
DocFileSuite には、キーワード引数でオプションを指定できます:
オプション引数module_relative はpaths に指定したファイル名を どのように解釈するかを指定します:
True (デフォルト) の場合、
filename は OS に依存しないモジュールの相対パスになります。
デフォルトでは、このパスは関数 testfile を呼び出して
いるモジュールからの相対パスになります; ただし、package
引数を指定した場合には、パッケージからの相対になります。
OS への依存性を除くため、filename ではパスを分割する
文字に/ を使わねばならず、絶対パスにしてはなりません
(パス文字列を/ で始めてはなりません)。
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 パラメタが追加されました
| [module][, globs][, extraglobs][, test_finder][, setUp][, tearDown][, checker]) |
この関数の返す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 サポート に特化したレポートフラグ表記方法もサポートしています:
| flags) |
引数flags にはオプションフラグを OR で結合して渡します。 23.2.6 節を参照してください。「レポートフラグ」 しか使えません。
この関数で設定した内容はモジュール全体にわたる物であり、関数呼び出し 以後に unittest モジュールから実行される全ての doctest に影響します: DocTestCase のrunTest() メソッド は、DocTestCase インスタンスが作成された際に、現在の テストケースに指定されたオプションフラグを見に行きます。 レポートフラグが指定されていない場合 (通常の場合で、望ましいケースです)、 doctest の unittest レポートフラグが OR で 結合され、doctest を実行するために作成されるDocTestRunner インスタンスに渡されます。 DocTestCase インスタンスを構築する際に何らかのレポートフラグが 指定されていた場合、doctest のunittest レポートフラグは無視されます。
この関数は、関数を呼び出す前に有効になっていたunittest レポートフラグの値を返します。
バージョン 2.4 で 新たに追加 された仕様です。
|
|
|
Python ライブラリリファレンス | |
|
|