【Python】doctestモジュールでインタラクティブなコード例を自動テストする方法

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

テスト対象となる例は、クラス、モジュール、または関数内のdocstring（ドキュメンテーション文字列）から抽出されます。また、別途用意したテキストファイルからdoctestを実行することも可能です。

docstringとは何か

Pythonにおける「docstring」とは、クラス、関数、またはモジュールの先頭に記述される文字列リテラルのことです。プログラムの実行時には無視されますが、コンパイラによって認識され、そのクラス・関数・モジュールの __doc__ 属性に格納されます。

docstringは通常、Pythonコードの各部分の使い方を説明するために記述されます。doctestモジュールを利用すれば、コードの改訂が繰り返されても、docstring内の使用例が常に最新の状態であるかどうかを簡単に検証できます。

testmod()関数による基本的な使い方

以下のコードでは、add() 関数が定義されており、そのdocstring内に使用例が埋め込まれています。使用例が正しいかどうかを検証するには、doctestモジュールの testmod() 関数を呼び出します。

def add(a,b):
'''
>>> add(10,20)
30
>>> add('aaa','bbb')
'aaabbb'
>>> add('aaa',20)
Traceback (most recent call last):
...
TypeError: must be str, not int
'''
return a+b

上記のスクリプトを mytest.py という名前で保存し、コマンドラインから実行してみましょう。

python mytest.py

テストが失敗しない限り、何も出力されません。次に、コマンドラインを以下のように変更して実行します。

python mytest.py -v

-v オプションを付けると、詳細モードで実行され、コンソールには以下のような結果が表示されます。

F:\Python36>python mytest.py -v
Trying:
add(10,20)
Expecting:
30
ok
Trying:
add('aaa','bbb')
Expecting:
'aaabbb'
ok
Trying:
add('aaa',20)
Expecting:
Traceback (most recent call last):
...
TypeError: must be str, not int
ok
1 items had no tests:
__main__
1 items passed all tests:
3 tests in __main__.add
3 tests in 2 items.
3 passed and 0 failed.
Test passed.

テキストファイル内の例をチェックする

doctestのもうひとつのシンプルな応用例が、テキストファイル内に書かれたインタラクティブな例をテストすることです。これには testfile() 関数を使用します。

たとえば、以下のテキストが example.txt という名前のテキストファイルに保存されているとします。

Using ''add''
-------------------
This is an example text file . First import
''add'' from the ''mytest'' module:
>>> from mytest import add
>>> add(10,20)
30

ファイルの内容はdocstringと同じように扱われます。テキストファイル内の例を検証するには、doctestモジュールの testfile() 関数を次のように使います。

def add(a,b):
return a+b
if __name__ == "__main__":
import doctest
doctest.testfile("example.txt")

doctest利用時の注意点

• testmod() と同様に、testfile() もテストが失敗しない限り何も表示しません。失敗した場合は、失敗した例とその原因が testmod() と同じ形式でコンソールに出力されます。

• 多くの場合、インタラクティブなコンソールセッションをそのままコピー＆ペーストすれば正常に動作しますが、doctestは特定のPythonシェルを厳密にエミュレートしようとするものではない点に注意してください。

• 期待される出力は、コードを含む最後の「>>>」または「...」行の直後に続けなければなりません。期待される出力（ある場合）は、次の「>>>」行または空白のみの行までが範囲となります。

• 期待される出力の中に空白のみの行を含めることはできません。空白のみの行は出力の終了を意味するものと解釈されるためです。もし期待される出力に空行が含まれる場合は、空行が現れるべき箇所に <BLANKLINE> を明示的に記述してください。

この記事では、doctestモジュールの主要な機能である testmod() 関数と testfile() 関数について解説しました。docstringに記述した使用例をそのままテストケースとして活用できるdoctestは、ドキュメントとコードの整合性を保ちながらリグレッションテストを行うのに非常に便利なツールです。