23.2 doctest -- 対話モードを使った使用例の内容をテストする

doctest モジュールは、対話的 Python セッションのように見えるテキストを探し出し、セッションの内容を実行して、そこに書かれている通りに振舞うかを調べます。 doctest は以下のような用途によく使われています:

doctest モジュールは、モジュールの docstring から、これらのセッションを実際に実行して、そこに書かれている通りに動作するか検証します。

"""
This is the "example" module.

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

>>> factorial(5)
120
"""

def factorial(n):
    """Return the factorial of n, an exact integer >= 0.

    If the result is small enough to fit in an int, return an int.
    Else return a long.

    >>> [factorial(n) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> [factorial(long(n)) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> factorial(30)
    265252859812191058636308480000000L
    >>> factorial(30L)
    265252859812191058636308480000000L
    >>> factorial(-1)
    Traceback (most recent call last):
        ...
    ValueError: n must be >= 0

    Factorials of floats are OK, but the float must be an exact integer:
    >>> factorial(30.1)
    Traceback (most recent call last):
        ...
    ValueError: n must be exact integer
    >>> factorial(30.0)
    265252859812191058636308480000000L

    It must also not be ridiculously large:
    >>> factorial(1e100)
    Traceback (most recent call last):
        ...
    OverflowError: n too large
    """

    import math
    if not n >= 0:
        raise ValueError("n must be >= 0")
    if math.floor(n) != n:
        raise ValueError("n must be exact integer")
    if n+1 == n:  # catch a value like 1e300
        raise OverflowError("n too large")
    result = 1
    factor = 2
    while factor <= n:
        result *= factor  
        factor += 1
    return result

def _test():
    import doctest
    doctest.testmod()

if __name__ == "__main__":
    _test()

example.py をコマンドラインから直接実行すると、 doctest はその魔法を働かせます:

$ python example.py
$

出力は何もありません！しかしこれが正常で、全ての例が正しく動作することを意味しています。スクリプトに -v を与えると、doctest は何を行おうとしているのかを記録した詳細なログを出力し、最後にまとめを出力します:

$ python example.py -v
Trying:
    factorial(5)
Expecting:
    120
ok
Trying:
    [factorial(n) for n in range(6)]
Expecting:
    [1, 1, 2, 6, 24, 120]
ok
Trying:
    [factorial(long(n)) for n in range(6)]
Expecting:
    [1, 1, 2, 6, 24, 120]
ok

Trying:
    factorial(1e100)
Expecting:
    Traceback (most recent call last):
        ...
    OverflowError: n too large
ok
1 items had no tests:
    __main__._test
2 items passed all tests:
   1 tests in __main__
   8 tests in __main__.factorial
9 tests in 3 items.
9 passed and 0 failed.
Test passed.
$

これが、doctest を使って生産性の向上を目指す上で知っておく必要があることの全てです！さあやってみましょう。詳細な事柄は後続の各節で全て説明しています。 doctest の例は、標準の Python テストスイートやライブラリ中に沢山あります。標準のテストファイル Lib/test/test_doctest.py には、特に便利な例題があります。

doctest.py 内の docstring には doctest の全ての側面についての詳細な情報が入っており、ここではより重要な点をカバーするだけにします。