5.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 の全ての側面に ついての詳細な情報が入っており、ここではより重要な点をカバーするだけに します。



ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。