23.2.2 簡単な利用法: テキストファイル中の例題をチェックする

doctest のもう一つの簡単な用途は、テキストファイル中にある対話操作の例に対するテストです。これには testfile() 関数を使います:

import doctest
doctest.testfile("example.txt")

この短いスクリプトは、example.txt というファイルの中に入っている対話モードの Python 操作例全てを実行して、その内容を検証します。ファイルの内容は一つの巨大な docstring であるかのように扱われます; ファイルが Python プログラムでなくてもよいのです！例えば、 example.txt には以下のような内容が入っているかもしれません:

The ``example`` module
======================

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(6)
    120

doctest.testfile("example.txt") を実行すると、このドキュメント内のエラーを見つけ出します:

File "./example.txt", line 14, in example.txt
Failed example:
    factorial(6)
Expected:
    120
Got:
    720

testmod() と同じく、testfile() は例題が失敗しない限り何も表示しません。例題が失敗すると、失敗した例題とその原因が (場合によっては複数) testmod() と同じ書式で標準出力に書き出されます。

デフォルトでは、testfile() は自分自身を呼び出したモジュールのあるディレクトリを探します。その他の場所にあるファイルを見に行くようにtestfile() に指示するためのオプション引数についての説明は 23.2.7 節を参照してください。

testmod() と同様、コマンドラインオプション-v またはオプションのキーワード引数 verbose を使うと、 testfile() の冗長度を設定できます。