doctestとは

doctestは、Python標準で用意されているテストモジュールの一種で、docstring内に記載したテスト内容を対話的にテストするためのものです。doctestの公式ドキュメントはこちらを参照してください。

docstringとは、以下の例のようにPythonプログラムのクラスや関数の定義の先頭に”””で囲まれる文字列として記載するもので、各処理などの説明を記載するものを言います。

class Sample:
    """Sampleクラス"""

    def add_and_double(self, x, y):
        """xとyを足して2倍した値を返却する

        Args:
            x: 入力値1
            y: 入力値2

        Raises:
            ValueError: int以外の場合

        Returns:
            (x + y) * 2 の計算結果
        """

なお、上記のdocstringの記載スタイルはGoogleスタイルと呼ばれるもので、他にも有名なところではNumPyスタイルといった記載方法もあります。

さて、doctestに戻りますが、doctestはdocstring内にテストを記載することでテストケースの実行ができます。また、docstring内に入出力例が記載されるのでドキュメントとしても分かりやすくなるという利点があります。

この記事では、doctestの基本的な使い方について紹介します。

doctestの使い方

基本的な使い方

ここからは具体的にdoctestを使用したテストの例を見ていきましょう。doctestを使用する際には、以下のプログラム例(doctest_sample.py)のように実装します。

今回はSampleクラスに定義したadd_and_doubleという簡単なメソッドをテストする例を使って説明していきます。まずは、プログラム全体を示して、細部については以降で順に説明していきます。

class Sample:
    """Sampleクラス"""

    def add_and_double(self, x, y):
        """xとyを足して2倍した値を返却する

        Args:
            x: 入力値1
            y: 入力値2

        Raises:
            ValueError: int以外の場合

        Returns:
            (x + y) * 2 の計算結果

        >>> tmp = Sample()
        >>> tmp.add_and_double(1, 1)
        4
        >>> tmp.add_and_double(2, 2)
        8
        >>> tmp.add_and_double("1", 1)
        Traceback (most recent call last):
        ...
        ValueError
        """
        # intでない場合は、ValueErrorとする
        if not isinstance(x, int) or not isinstance(y, int):
            raise ValueError

        # 計算処理
        result = x + y
        result *= 2

        return result


if __name__ == "__main__":
    import doctest

    # doctestを実行
    doctest.testmod()

なお、doctestではテストOKの場合、基本は何も表示されません。

python doctest_sample.py

そのため、上記のようにプログラムを実行しても何も表示されません。

基本的な構成

doctestでは、docstring内に以下のようにテストコードを記載します。以下は一部抜粋しています。

    def add_and_double(self, x, y):
        """xとyを足して2倍した値を返却する

        ...(省略)...

        >>> tmp = Sample()
        >>> tmp.add_and_double(1, 1)
        4

        ...(省略)...
        """

docstring内で、「>>>」で記載した行はPythonで実際に実行するプログラム行になっています。上記はSampleクラスをtmpでインスタンス化し、tmp.add_and_double(1,1)を実行しています。この時、正解は(1 + 1) × 2 = 4なので、その下に「4」という比較すべき答えを記載します。

doctest自体は以下の部分で実行されています。

if __name__ == "__main__":
    import doctest

    # doctestを実行
    doctest.testmod()

上記はdoctestをインポートして、doctest.testmod()が具体的にテストを実行しています。

if __name__ == “__main__”:のブロックに記載しておくと、外部プログラムからライブラリとして呼び出されたときには実行されません。コマンドラインで__main__として呼び出されたときのみテストが実行されることになります。

なお、テスト成功の場合は、何も結果に表示はされません。

テストが失敗する場合

では、テストが失敗する場合を見てみましょう。例えば以下のようにすると、メソッドの返却値とテスト値が異なるので失敗となります。

    def add_and_double(self, x, y):
        """xとyを足して2倍した値を返却する

        ...(省略)...

        >>> tmp = Sample()
        >>> tmp.add_and_double(1, 1)
        8

        ...(省略)...
        """

**********************************************************************
File "d:\PythonProjects\python-tech-sample-source\python-tech-sample-source\python-libraries\doctest\doctest_sample.py", line 29, in __main__.Sample.add_and_double
Failed example:
    tmp.add_and_double(1, 1)
Expected:
    8
Got:
    4
**********************************************************************
1 items had failures:
   1 of   4 in __main__.Sample.add_and_double
***Test Failed*** 1 failures.

上記のようにメソッドからの返却値は4で、テストとして期待していたのが8なので一致せずにFailedということになります。

なお、この例は、返却値は正しいわけですので、テストケースをミスしていた場合です。テストの失敗としては「テスト対象プログラムの処理結果が誤っている場合」や上記のように「テストケース自体が誤っているような場合」等、色々ありますのでエラーを見つつ、プログラムを修正していくようにしてください。

例外の確認方法

次に、例外処理をテストする場合のテストメソッドの記載方法です。

    def add_and_double(self, x, y):
        """xとyを足して2倍した値を返却する

        ...(省略)...

        >>> tmp.add_and_double("1", 1)
        Traceback (most recent call last):
        ...
        ValueError
        """

今回のテスト対象プログラムsample.pyのadd_and_doubleメソッドでは、intではない引数が渡された場合にValueErrorを返却することになっています。

この場合出力結果は「Traceback (most recent call last):～省略～ValueError」というような出力結果となります。

doctestでこのような値との一致をみるときは、先頭の「Traceback (most recent call last):」と最後の「ValueError」部分を記載して、途中は「…」と記載することで一致を確認することができます。

もし「tmp.add_and_double(1, 1)」のように例外をあげないような処理を記載するとテストは失敗となります。

ちょっとした注意点

doctestを使用する際にちょっとした注意点があります。テスト対象のプログラム名を「doctest.py」としてしまうと、以下のようにtestmodがないということでAttributeErrorが出力されてしまいます。

AttributeError: module 'doctest' has no attribute 'testmod'

私がdoctestのサンプルプログラムを作ろうと思って安易に「doctest.py」としたことで、少しはまってしまいました。

皆さんが普段テストするようなファイルがこのようなファイル名になっていることは、ほぼないかと思うので大丈夫だと思いますが、覚え書きということで記載しておきます。

処理結果の詳細表示方法

上記で説明した通りdoctestでは、テストOKの場合にはなにも出力されません。詳細表示を必ず表示したい場合には、以下に紹介する方法が使用できます。

実行時に「-v」を指定して実行する

処理結果の詳細表示をテストOKでも表示したい場合は、以下のようにプログラム実行時のコマンドライン引数で「-v」を指定します。

python doctest_sample.py -v

この際の出力結果は以下のようになります。

> python .\doctest_sample.py -v
Trying:
    tmp = Sample()
Expecting nothing
ok
Trying:
    tmp.add_and_double(1, 1)
Expecting:
    4
ok
Trying:
    tmp.add_and_double(2, 2)
Expecting:
    8
ok
Trying:
    tmp.add_and_double("1", 1)
Expecting:
    Traceback (most recent call last):
    ...
    ValueError
ok
2 items had no tests:
    __main__
    __main__.Sample
1 items passed all tests:
   4 tests in __main__.Sample.add_and_double
4 tests in 3 items.
4 passed and 0 failed.
Test passed.

doctest.testmodにverbose=Trueを設定する

処理結果の詳細表示をテストOKでも表示したい場合のもう一つの方法としては、以下のようにdoctest.testmodの引数でverbose=Trueを設定します。

if __name__ == "__main__":
    import doctest

    # doctestを実行
    doctest.testmod(verbose=True)

上記のように実装しておくと実行時に「-v」をつけなくても詳細が表示されます。

> python .\doctest_sample.py   
Trying:
    tmp = Sample()
Expecting nothing
ok
Trying:
    tmp.add_and_double(1, 1)
Expecting:
    4
ok
Trying:
    tmp.add_and_double(2, 2)
Expecting:
    8
ok
Trying:
    tmp.add_and_double("1", 1)
Expecting:
    Traceback (most recent call last):
    ...
    ValueError
ok
2 items had no tests:
    __main__
    __main__.Sample
1 items passed all tests:
   4 tests in __main__.Sample.add_and_double
4 tests in 3 items.
4 passed and 0 failed.
Test passed.

まとめ

Pythonプログラムをdoctestを使ってテストする方法について解説しました。

doctestは、Python標準で用意されているテストモジュールの一種でdocstring内にテストを記載することでテストケースの実行ができます。また、docstring内に入出力例が記載されるのでドキュメントとしても分かりやすくなるという利点があります。

手軽にテストできるモジュールとして是非doctestを使ってみてもらえればと思います。

あわせて読みたい

【Python Tech】プログラミングガイド

Pythonにおけるdocstring

Pythonでプログラミング開発をしている際に、関数やクラスなどの仕様を利用者に対して分かるようにすることが必要です。ダブルクオート(“)を３つ連続して並べた三重引用符で囲んで記載した文字列をdocstringと言います。

例えば、docstringの例としては以下のような感じです。

def sample_func(temp1: int, temp2: int) -> int:
    """2変数の加算結果を返却する

    Args:
        temp1 (int): 数値1
        temp2 (int): 数値2

    Returns:
        int: 加算結果
    """
    return temp1 + temp2

このdocstringについては、自分でゼロから書いてももちろんいいのですが、関数の定義をベースに自動で生成して、細部を埋めていく方がはるかに楽です。

コードエディタであるVSCodeでは、拡張機能である「Python Docstring Generator」を使用することで、docstringを自動生成することが可能になります。

本記事では、Python Docstring Generatorをインストールや使い方、設定方法について紹介します。

Python Docstring Generatorの使い方

Python Docstring Generatorのインストール

Python Docstring Generatorは、Python拡張機能としてインストールできます。以下の手順でPython拡張機能をインストールしてください。

1. 拡張タブを選択する。
2. 検索窓で「docstring」と入力する。
3. 検索された「autoDocstring – …」をクリックすると右側にPython拡張の説明が表示される。
4. インストールをクリックしてPython拡張機能をインストールする。

上記のインストールを行うことでPython Docstring Generatorの機能が使用できるようになります。

Python Docstring Generatorの使い方

Python Docstring Generatorの使い方は簡単です。

開発しているPythonプログラムで関数を定義するときに、関数定義の下の行で以下のようにダブルクオート(“)を三つ入力すると「Generate Docstring」というように表示されるのでEnterを押します。

また、ダブルクオートを入力しなくても関数定義の下の行で「ctrl + shift + 2」とすることでも生成できますのでお好みの方法を利用してください。

実行すると以下のようにdocstringが自動生成されます。

_summary_や_description_のところを以下のように自分で書き換えればdocstringが完成します。

docstringを記載しておくと、以下のように呼び出しもとで関数にマウスのカーソルを合わせる等するだけ以下のように、関数の概要を把握することも可能になります。

Python Docstring Generatorの設定

Python Docstring Generatorでは、「google」スタイルのフォーマットがデフォルト設定となっています。

拡張機能のインストール一覧からPython Docstring Generatorの[歯車マーク]-[拡張機能の設定]をクリックすると設定を確認することができます。

以下のAuto Docstring: Docstring Formatの部分がフォーマットに関する設定になります。

プルダウンをクリックして見ると以下のように結構たくさんの種類がありますね。自分の好みやプロジェクトの方針により設定を変更して使用してください。

どのスタイルを使うのがよいのかという話があるかと思います。numpyスタイルか、googleスタイルかといったあたりがよく話が上がるような気がしますが、プロジェクトとして一貫していればいずれのフォーマットでも問題ないかと思います。

まとめ

VSCodeでのPython開発でdocstringを自動生成してくれるPython Docstring Generatorについて紹介しました。

Python Docstring Generatorのインストール、基本的な使い方、スタイルの設定について説明しています。docstringの記載は関数等の説明を利用者やプロジェクトメンバに伝える意味でも、プログラミングにおいて重要なことであると思っています。

ゼロから自分で書くのは少し面倒ですので、Python Docstring Generatorを活用して効率よく記載していってもらえるとよいかと思います。

あわせて読みたい

【Python Tech】プログラミングガイド