ドキュメントテスト

doctest は、 Pythonプログラミング言語の標準ライブラリに含まれるモジュールで、標準の Python インタープリタ シェルからの出力に基づいてテストを簡単に生成し、それをdocstringに切り取って貼り付けることができます。

Doctestは、以下のPythonの機能を革新的に^{[1]活用しています: [2]}

• ドキュメント文字列
• Python 対話型シェル (コマンドラインと付属のアイドル アプリケーションの両方)
• Pythonイントロスペクション

Python シェルを使用する場合、プライマリ プロンプト: >>>の後に新しいコマンドが続きます。セカンダリ プロンプト: ...は、コマンドを複数行に継続するときに使用され、コマンドの実行結果は次の行に表示されます。空白行、またはプライマリ プロンプトで始まる別の行は、コマンドからの出力の終了と見なされます。

doctest モジュールは、docstring 内でこのようなプロンプトのシーケンスを探し、抽出されたコマンドを再実行し、その出力を docstrings テスト例で指定されたコマンドの出力と比較します。

doctest を実行するときのデフォルトのアクションでは、テストが合格しても出力は表示されません。これは、doctest ランナーのオプションによって変更できます。さらに、doctest は Python ユニット テスト モジュールと統合されており、doctest を標準のユニット テスト テストケースとして実行できます。ユニット テスト テストケース ランナーでは、合格したテストや失敗したテストなどのテスト統計のレポートなど、テスト実行時にさらに多くのオプションを使用できます。

doctest では Python プログラムを説明文に埋め込むことはできませんが、検証可能な例を docstring に埋め込むことはできます。docstring には他のテキストを含めることができます。docstring はプログラム ファイルから抽出して、HTML や PDF などの他の形式でドキュメントを生成することもできます。プログラム ファイルには、ドキュメント、テスト、コード、コードと簡単に照合できるテストを含めることができます。これにより、コード、テスト、ドキュメントを一緒に進化させることができます。

Doctest は、API の使用方法を示すことでライブラリの概要を説明するのに適しています。

Python のインタラクティブ インタープリターの出力に基づいて、ライブラリを実行するテストとテキストを混合し、期待される結果を表示できます。

例 1 は、docstring 内で説明文をテスト可能な例とどのように組み合せることができるかを示しています。2 番目の例では、doctest のその他の機能とその説明を示します。例 3 は、ファイルの実行時にファイル内のすべての doctest を実行するように設定されていますが、モジュールとしてインポートされると、テストは実行されません。

def  list_to_0_index ( lst ): 
"""問題の解決策は、次のサイトに記載されています:     https://rgrig.blogspot.com/2005/11/writing-readable-code.html    



    「リスト lst が与えられ、各要素が最初
    に出現する 0 インデックスがあるとします。したがって、リスト x = [0, 1, 4, 2     , 4, 1, 0, 2] は y = [0, 1, 2, 3, 2, 1, 0, 3] に変換されます。すべての i について x[y[i]] = x[i] であることに注意してください
    。任意のプログラミング言語と任意のデータ
    表現を使用できます。」

    >>> x = [0, 1, 4, 2, 4, 1, 0, 2] 
    >>> list_to_0_index(x) 
    [0, 1, 2, 3, 2, 1, 0, 3] 
    >>> 
    """

     [ lst.index ( i )を返す( iはlst内)]    

======================
デモンストレーション doctest 
======================


これは、Python の doctest モジュールの doctest.DocFileSuite() 関数で使用できる README テキストの例です。

通常、README ファイルでは、次のようにモジュールの API について説明します。

>>> a  =  1 
>>> b  =  2 
>>> a  +  b 
3

Python で 2 つの数値を加算する方法と、
その結果がどのようになるかについて説明しました。

特別なオプションを使用すると、例をある程度曖昧にすることができます。

>>> o  =  object () 
>>> o                  # doctest: +ELLIPSIS 
<object object at 0x...>

例外も非常にうまくテストできます。

>>> x
トレースバック (最後の呼び出し): 
... NameError :名前 'x' は定義されていません 

この例では、Python StringIOモジュールを使用してファイルから関数への入力をシミュレートします。

def  unique_words ( page ): 
"""テキスト行のリスト内の一意の単語のセットを返します。    

    例：

    >>> from StringIO import StringIO 
    >>> fileText = '''猫はマットの上に座っていました
    ...マットは猫の上にありました
    ...1匹の魚、2匹の魚、赤い魚
    ...青い魚
    ...この魚には黄色い車があります
    ...この魚には黄色い星があります''' 
    >>> file = StringIO(fileText) 
    >>> page = file.readlines() 
    >>> words = unique_words(page) 
    >>> print sorted(list(words)) 
    ["This", "a", "blue", "car", "cat", "fish", "has", "mat", 
     "on", "ondur", "one", "red", "sat", "star", "the", "two", 
     "was", "yellow"] 
    >>> 
    """ 
    return  set ( word  for  line  in  page  for  word  in  line . split ())

def  _test ( ): 
    doctestをインポートします 。doctest.testmod ()
    

 __name__  ==  "__main__"の場合: 
    _test ()

Epydocの EpyText 形式と Docutils のreStructuredText形式はどちらも、docstring 内の doctest セクションのマークアップをサポートしています。

C++では、doctestフレームワークがこの概念に最も近い実装です。テストは、最小限のオーバーヘッドで本番コードに直接記述でき、バイナリからテストを削除するオプションがあります。^[3]

ExUnit.DocTest ElixirライブラリはDoctestに似た機能を実装しています。^[4]

Haskell用のDoctestの実装。^[5]

Elmでドキュメントテストを書く。^[6]

Rustでドキュメントテストを書く。^[7]

Elixirでドキュメントテストを書く。^[8]

byexample^[9]は、 Markdown、reStructuredText 、その他のテキストドキュメント内で、いくつかの一般的なプログラミング言語（Python、Ruby、Shell、JavaScript、C / C ++、Java、Go、Rustなど）のdoctestの作成をサポートしています。

• doctest — インタラクティブな Python サンプルをテストする