ソフトウェア開発では、コードの動作確認を行うテストが重要です。しかし、テストケースを別途記述するのは手間がかかる場合があります。

doctestモジュールは、Pythonコード内に記述されたドキュメント（docstring）をそのままテストケースとして活用することで、この課題を解決します。簡単なサンプルコード付きのドキュメントを作成するだけで、コードの動作確認が可能になります。

doctestとは

doctestの概要

doctestは、Python標準ライブラリに含まれるモジュールで、docstringに記述されたサンプルコードを自動的に実行し、その出力が期待される結果と一致するかを確認します。

doctestの主なメリット

1. 簡単なテスト作成
   サンプルコードをdocstringに記述するだけで、テストが自動的に作成されます。
2. ドキュメントの一貫性向上
   実行可能なサンプルコードを記載することで、ドキュメントと実際のコードの整合性を保てます。
3. 手軽な導入
   Python標準ライブラリのため、追加のインストールが不要です。

doctestの基本的な使い方

サンプルコードをdocstringに記述

以下のように、関数やクラスのdocstring内にサンプルコードを記述します。

def add(a, b):
    """
    二つの数値を加算します。

    >>> add(1, 2)
    3
    >>> add(-1, 1)
    0
    """
    return a + b

doctestを実行

doctestを使用してテストを実行するには、以下の2つの方法があります。

方法1：スクリプト内で直接実行

if __name__ == "__main__":
    import doctest
    doctest.testmod()

方法2：コマンドラインで実行

python -m doctest -v example.py

実行結果

成功した場合は以下のような結果が表示されます：

1 items passed all tests:
   2 tests in example.add
2 tests in 1 items.
2 passed and 0 failed.
Test passed.

失敗した場合は、期待値と実際の出力が表示されます。

doctestの応用

複数行の出力をテスト

doctestは複数行にわたる出力にも対応しています。

例：複数行の出力

def greet(name):
    """
    指定した名前で挨拶をします。

    >>> greet("Alice")
    Hello, Alice!
    How are you today?
    """
    return f"Hello, {name}!\nHow are you today?"

任意のテキストを無視する

特定の部分を無視する場合、...を使用します。

例：一部を無視する

def example():
    """
    テキストの一部を無視します。

    >>> example()
    Result:
    ...
    """
    return "Result:\nLine1\nLine2"

外部モジュールのテスト

doctestは外部モジュール内のdocstringもテストできます。

例：外部モジュールを指定してテスト

python -m doctest -v external_module.py

doctestを使う際の注意点

1. 複雑なテストには不向き
   複雑なロジックや多数の条件分岐がある場合は、unittestやpytestなどのテストフレームワークを併用しましょう。
2. フォーマットに注意
   サンプルコードとその出力は正確に記述する必要があります。インデントや改行が異なるとエラーになります。
3. 外部リソースの使用
   ファイル操作やネットワーク通信を伴うテストには向きません。

doctestと他のテストフレームワークの比較

まとめ

Pythonのdoctestモジュールは、コードのドキュメント化とテストを同時に行える便利なツールです。本記事で紹介した基本操作や応用例を参考に、doctestを活用してコードの品質向上を目指しましょう！