UnitTest Framework-Doctest

Pythonの標準ディストリビューションには「Doctest」モジュールが含まれています。このモジュールの機能により、インタラクティブなPythonセッションのように見えるテキストを検索し、これらのセッションを実行して、表示どおりに機能するかどうかを確認できます。

Doctestは、次のシナリオで非常に役立ちます-

モジュールのドキュメント文字列が最新であることを確認するには、すべてのインタラクティブな例がドキュメントどおりに機能することを確認します。
テストファイルまたはテストオブジェクトからの対話型の例が期待どおりに機能することを確認して、回帰テストを実行します。
パッケージのチュートリアルドキュメントを書くために、入出力の例で自由に説明します

Pythonでは、「docstring」は、クラス、関数、またはモジュールの最初の式として表示される文字列リテラルです。スイートの実行時には無視されますが、コンパイラーによって認識され、クラス、関数、またはモジュールを囲む doc 属性に格納されます。イントロスペクションを介して利用できるため、オブジェクトのドキュメント化の標準的な場所です。

Pythonコードのさまざまな部分の使用例をdocstring内に配置するのは通常の方法です。 doctestモジュールを使用すると、これらのdocstringがコードの断続的な改訂により最新であることを確認できます。

次のコードでは、使用例が散在した階乗関数が定義されています。サンプルの使用法が正しいかどうかを確認するには、doctestモジュールでtestmod（）関数を呼び出します。

"""
This is the "example" module.

The example module supplies one function, factorial(). For example,

>>> factorial(5)
120
"""

def factorial(x):
   """Return the factorial of n, an exact integer >= 0.
   >>> factorial(-1)
   Traceback (most recent call last):
      ...
   ValueError: x must be >= 0
   """

   if not x >= 0:
      raise ValueError("x must be >= 0")
   f = 1
   for i in range(1,x+1):
      f = f*i
   return f

if __name__ == "__main__":
   import doctest
   doctest.testmod()

上記のスクリプトを入力してFactDocTest.pyとして保存し、コマンドラインからこのスクリプトを実行してみます。

Python FactDocTest.py

例が失敗しない限り、出力は表示されません。さて、次のようにコマンドラインを変更します-

Python FactDocTest.py –v

コンソールには、次の出力が表示されます-

C:\Python27>python FactDocTest.py -v
Trying:
   factorial(5)
Expecting:
   120
ok
Trying:
   factorial(-1)
Expecting:
   Traceback (most recent call last):
      ...
   ValueError: x must be >= 0
ok
2 items passed all tests:
   1 tests in __main__
   1 tests in __main__.factorial
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

一方、factorial（）関数のコードがdocstringに期待される結果を与えない場合、失敗の結果が表示されます。たとえば、上記のスクリプトのf = 1の代わりにf = 2を変更し、doctestを再度実行します。結果は次のようになります-

Trying:
   factorial(5)
Expecting:
   120
**********************************************************************
File "docfacttest.py", line 6, in __main__
Failed example:
factorial(5)
Expected:
   120
Got:
   240
Trying:
   factorial(-1)
Expecting:
   Traceback (most recent call last):
      ...
   ValueError: x must be >= 0
ok
1 items passed all tests:
   1 tests in __main__.factorial
**********************************************************************
1 items had failures:
   1 of 1 in __main__
2 tests in 2 items.
1 passed and 1 failed.
***Test Failed*** 1 failures.

Doctest：テキストファイルの例を確認する

doctestのもう1つの単純なアプリケーションは、テキストファイル内のインタラクティブな例をテストすることです。これは、testfile（）関数を使用して実行できます。

次のテキストは、「example.txt」という名前のテキストファイルに保存されます。

Using ''factorial''
-------------------
This is an example text file in reStructuredText format. First import
''factorial'' from the ''example'' module:
   >>> from example import factorial
Now use it:
   >>> factorial(5)
   120

ファイルの内容はdocstringとして扱われます。テキストファイル内の例を確認するには、doctestモジュールのtestfile（）関数を使用します。

def factorial(x):
   if not x >= 0:
      raise ValueError("x must be >= 0")
   f = 1
   for i in range(1,x+1):
      f = f*i
   return f

if __name__ == "__main__":
   import doctest
   doctest.testfile("example.txt")

testmod（）と同様に、testfile（）は例が失敗しない限り何も表示しません。例が失敗した場合、testmod（）と同じ形式を使用して、失敗した例と失敗の原因がコンソールに出力されます。
ほとんどの場合、インタラクティブコンソールセッションのコピーアンドペーストは正常に機能しますが、doctestは特定のPythonシェルを正確にエミュレートしようとはしていません。
予想される出力は、最後の「>>>」または「… 'コードを含む行と、予想される出力（存在する場合）は、次の' >>> 'またはすべて空白の行に拡張されます。
期待される出力には、すべて空白の行を含めることはできません。そのような行は、予想される出力の終わりを知らせるために使用されるためです。予想される出力に空白行が含まれる場合、doctestの例に空白行が予想される各場所に<BLANKLINE>を入れます。

Unittest-framework-doctest

UnitTest Framework-Doctest

Doctest：テキストファイルの例を確認する