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

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

- モジュールの docstring (ドキュメンテーション文字列) 中にある対話 モードでの使用例全てが書かれている通りに動作するかを検証することで、 docstring の内容が最新のものになるよう保ちます。
- テストファイルやテストオブジェクト中の対話モードにおける使用例が 期待通りに動作するかを検証することで、回帰テストを実現します。
- 入出力例をふんだんに使ったパッケージのチュートリアルドキュメントを 書けます。入出力例と解説文のどちらに注目するかによって、ドキュメントは 「読めるテスト」にも「実行できるドキュメント」にもなります。

以下にちょっとした、それでいて完全な例を示します:

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