ステージ1: docstring + doctest + pydoc (情報工学実験 4 : データマイニング班)

• コード例（my_math.py）を準備。これは階乗を求めるコード例。これを元にユニットテストを記述＋実行してみよう。
• Step1: ユニットテストを記述。
  • my_math.pyには階乗を計算するfactR()関数が定義されている。この関数が正しく動作することを検証するコードを、doctestで書いてみよう。ここでは「3の階乗は6」「4の階乗は24」であることを検証してみる。
  • ユニットテストを記述するツールとして、doctestを利用してみる。doctestは、docstring形式（"""〜"""）のコメント欄を利用する書き方。

    def factR(n):
        """
        ここはdocstring形式の、複数行に跨るコメント欄。
        単にコメントを書くためだけではなく、以下のようにdoctestを書くこともできる。
    
        >>> factR(3)
        6
        >>> factR(4)
        24
    
        以下は「doctestとして駄目な例」。>>>の次にスペースが入っていません。
        >>>factR(3)
        6
        """
        if n == 1:
            return n
        else:
            return n * factR(n-1)
    

  • 上記のようにmy_math.pyを編集・保存したら、ユニットテストを実行（Step2）してみよう。
• Step2: doctestを実行する。
  • コード内にdoctestモジュール読み込みを予め記述する方法と、実行時にオプション指定する方法がある。今回はオプション指定の方法で実行してみよう。

    # case 1: テストに失敗したときだけテスト結果を出力。
    python -m doctest my_math.py
    
    # case 2: 常にテスト結果を出力。
    python -m doctest my_math.py -v
    

• 補足
  • ユニットテストの一般的な使い方
    • 関数の仕様（入力と出力）を検討する際に、使い方の例示のためにテストを記載しておく。ここで書いたテストが通るように関数を仕上げていく。（テスト駆動開発）

      発展的な使い方: 中身は空のままで、先に関数名・引数・戻り値だけを決めていく。必要な関数群を列挙して全体が動く見通しを立てる。見通しが立ってから、中身の実装に入る。

    • 以前書いたコードに機能追加したくなった時、コード修正に伴い出力結果が変わっては困る。動作確認を自動化するためにテストを書いておく
  • doctestは「インタプリタで実行した際の結果をstr型で検証する」。ドキュメントの言葉を使うと「対話的 Python セッションのように見えるテキストを探し出し、セッションの内容を実行して、そこに書かれている通りに振舞うかを調べます」。
  • テストは1行でなくても良い。（下記コード例参照）

    def factR(n):
        """
        例1: 「factR(3) の結果が0より大きい数値であること」を検証するテストコード。
        >>> factR(3) > 0
        True
        >>> result = factR(3)
        >>> result > 0
        True
    
        例2: 「factR(3) の結果が0より大きい数値であり、かつ、int型であること」を検証するテストコード。
        >>> result = factR(3)
        >>> result > 0
        True
        >>> type(result)
        
        >>> result > 0 and type(result) == int
        True
        """
        if n == 1:
            return n
        else:
            return n * factR(n-1)