Pythonでdoctestを使ってドキュメントテスト

この記事では、Pythonのdoctestモジュールを使用して、ドキュメントとテストコードを同時に記述する方法を説明します。doctestを使うことで、コードの動作を明確に示し、テストを容易に行うことができます。

doctestの概要

doctestモジュールは、Pythonコードのdocstringの中にテストケースを記述し、実行できるモジュールです。 docstring内に期待される入出力例を記述することで、コードの動作を明確に示し、自動テストを行うことができます。

def add(x, y):
  """足し算を行う関数

  >>> add(2, 3)
  5
  >>> add(-1, 1)
  0
  """
  return x + y

シンプルな例

シンプルな関数の例を見てみましょう。docstring内に期待される入出力例を記述します。

def square(x):
  """数値の二乗を計算する関数

  >>> square(2)
  4
  >>> square(-3)
  9
  """
  return x * x

import doctest
doctest.testmod()

より複雑な例

複雑なデータ構造や条件分岐を含む関数でもdoctestを使用できます。

def is_even(n):
    """数値が偶数かどうかを判定する関数

    >>> is_even(2)
    True
    >>> is_even(3)
    False
    >>> is_even(0)
    True
    """
    return n % 2 == 0

import doctest
doctest.testmod()

setUpとtearDown

テストの前処理と後処理を行うには、setUpとtearDown関数を使用できます。

import doctest
import unittest

class TestMyFunctions(unittest.TestCase):
    def setUp(self):
        print("setUp")
        self.data = [1, 2, 3]

    def tearDown(self):
        print("tearDown")

    def test_add(self):
        self.assertEqual(add(2,3),5)

    def test_square(self):
        self.assertEqual(square(3),9)

if __name__ == '__main__':
    unittest.main()

テストの無視

doctest.IGNORE_EXCEPTION_DETAILフラグを使用して、特定の例外の詳細を無視できます。

import doctest

def my_function():
    """何らかの処理を行う関数
    >>> my_function()
    Traceback (most recent call last):
        ...
    Exception: Some Error
    """
    raise Exception("Some Error")

doctest.testmod(optionflags=doctest.IGNORE_EXCEPTION_DETAIL)

doctestの実行方法

コマンドラインからdoctestを実行するには、python -m doctest your_module.py を実行します。

IDEやテストランナーでも実行可能です。多くのエディタやIDEは、doctestを直接実行する機能を提供しています。

利点と欠点

利点: * ドキュメントとテストコードを同時に記述できる * テストケースがコードと一緒にメンテナンスされる * 読みやすい欠点: * 複雑なテストケースには向かない * テストの記述に制約がある * テストカバレッジが低い場合がある

PYTHON MEBY