Doctest

doctestは、Pythonプログラミング言語の標準ライブラリに含まれているモジュールで、標準のPythonインタープリターシェルからの出力に基づいて簡単にテストを生成し、docstringにカットアンドペーストできます。

実装の詳細

Doctestは、次のPython機能を革新的に使用します。

docstrings
Pythonインタラクティブシェル（コマンドラインと付属のアイドルアプリケーションの両方）。
Pythonイントロスペクション

Pythonシェルを使用する場合、プライマリプロンプト>>>の後に新しいコマンドが続きます。二次プロンプト：...は、複数の行でコマンドを続行するときに使用されます。そして、コマンドの実行結果は次の行で期待されます。空白行、またはプライマリプロンプトで始まる別の行は、コマンドからの出力の終わりとして表示されます。

doctestモジュールは、docstringでそのようなプロンプトのシーケンスを探し、抽出されたコマンドを再実行し、docstringsテスト例で指定されたコマンドの出力に対して出力をチェックします。

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

識字プログラミングとdoctest

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

例によるライブラリの文書化

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

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

例

例1は、ドキュメンテーション文字列内のテスト可能なサンプルに物語のテキストを散在させる方法を示しています。 2番目の例では、doctestのその他の機能とその説明が示されています。例3は、ファイルの実行時にファイル内のすべてのdoctestを実行するように設定されていますが、モジュールとしてインポートされた場合、テストは実行されません。

例1：関数のdocstringに埋め込まれたdoctest

def list_to_0_index（lst）： "" "次の問題の解決策：http://rgrig.blogspot.com/2005/11/writing-readable-code.html 0-indexが最初に現れる場所です。したがって、リストx =はy =に変換されます。すべてのiについて、xyiがあります。任意のプログラミング言語と任意のデータ表現を使用してください。 >>> x = >>> list_to_0_index（x）>>> "" "return

例2：README.txtファイルに埋め込まれたdoctest

======================デモンストレーションdoctests ======================これは単なるPythonのdoctestモジュールのdoctest.DocFileSuite（）関数で使用できるREADMEテキストの例。通常、READMEファイルは次のようにモジュールのAPIを説明します。>>> a = 1 >>> b = 2 >>> a + b 3注意、Pythonで2つの数値を追加する方法を示しただけで、結果はどのように見えるか。特別なオプションを使用すると、例について多少曖昧になります。>>> o = object（）>>> o＃doctest：+ ELLIPSIS 0xのオブジェクトオブジェクト...>例外も非常にうまくテストできます：>>> xトレースバック（最後の最後の呼び出し）：... NameError：name 'x'は定義されていません

例3：unique_words.py

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

def unique_words（page）： '' 'テキストの行のリストにある一意の単語のセットを返します例：>>> from StringIO import StringIO >>> fileText = "" "the cat sat on the mat ... the mat was ondur the cat ... one fish two fish red fish ... blue fish ...この魚は黄色の車を持っています...この魚は黄色の星を持っています "" ">>> file = StringIO（fileText）>>> page = file.readlines（）>>> words = unique_words（page）>>> print sort（list（words））>>> '' 'return set（word for page for line for word in line.split（）） def _test（）：__name__ == "__main__"の場合、doctest doctest.testmod（）をインポートします：_test（）

Doctestおよびドキュメントジェネレーター

EpydocのEpyText形式とDocutilsのreStructuredText形式の両方が、docstrings内のdoctestセクションのマークアップをサポートします。

他のプログラミング言語での実装

C ++では、doctestフレームワークがこの概念の最も近い実装です。テストは、最小限のオーバーヘッドでバイナリからテストを除去するオプションを使用して、実動コードに直接書き込むことができます。

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

HaskellのDoctestの実装。

Elmでドキュメントテストを作成します。

Rustでドキュメントテストを作成します。

byexample のdoctestに基づいやPython、 シェルやRubyのようないくつかの言語で文書のテストをサポートしています。

歴史

ソーシャル