UnitTest Framework-Doctest API

doctest APIは、docstringsからインタラクティブな例を保存するために使用される次の2つのコンテナクラスを中心に展開します-

例-期待される出力とペアになった単一のPythonステートメント。
DocTest -通常は単一のdocstringまたはテキストファイルから抽出されたサンプルのコレクション。

次の追加処理クラスは、doctestの例を検索、解析、実行、およびチェックするために定義されています-

DocTestFinder -指定されたモジュール内のすべてのdocstringを検索し、DocTestParserを使用して、インタラクティブな例を含むすべてのdocstringからDocTestを作成します。
DocTestParser -文字列（オブジェクトのdocstringなど）からdoctestオブジェクトを作成します。
DocTestRunner -doctestの例を実行し、OutputCheckerを使用して出力を検証します。
OutputChecker -doctestの例からの実際の出力を期待される出力と比較し、それらが一致するかどうかを判断します。

DocTestFinderクラス

これは、特定のオブジェクトに関連するdoctestを、そのdocstringおよび含まれるオブジェクトのdocstringから抽出するために使用される処理クラスです。 Doctestは現在、モジュール、関数、クラス、メソッド、staticmethods、classmethods、およびプロパティのオブジェクトタイプから抽出できます。

このクラスは、find（）メソッドを定義します。 object’s docstring、またはそれに含まれるオブジェクトのdocstringで定義されたDocTestのリストを返します。

DocTestParserクラス

文字列からインタラクティブな例を抽出し、それらを使用してDocTestオブジェクトを作成するために使用される処理クラスです。このクラスは、次のメソッドを定義します-

* get_doctest（）-指定された文字列からすべてのdoctestの例を抽出し、それらを *DocTest オブジェクトに収集します。
* get_examples（string [、name]）-指定された文字列からすべてのdoctestの例を抽出し、それらを *Example オブジェクトのリストとして返します。行番号は0から始まります。オプションの引数名は、この文字列を識別する名前であり、エラーメッセージにのみ使用されます。
* parse（string [、name]）*-指定された文字列を例と介入テキストに分割し、それらを*例*と文字列が交互に並んだリストとして返します。 *例*の行番号は0から始まります。オプションの引数名は、この文字列を識別する名前であり、エラーメッセージにのみ使用されます。

DocTestRunnerクラス

これは、DocTestのインタラクティブな例を実行および検証するために使用される処理クラスです。次のメソッドが定義されています-

report_start（）

テストランナーが特定の例を処理しようとしていることを報告します。このメソッドは、 DocTestRunner のサブクラスが出力をカスタマイズできるようにするために提供されています。直接呼び出さないでください

report_success（）

指定された例が正常に実行されたことを報告します。このメソッドは、DocTestRunnerのサブクラスが出力をカスタマイズできるようにするために提供されています。直接呼び出さないでください。

report_failure（）

指定された例が失敗したことを報告します。このメソッドは、 DocTestRunner のサブクラスが出力をカスタマイズできるようにするために提供されています。直接呼び出さないでください。

report_unexpected_exception（）

指定された例で予期しない例外が発生したことを報告します。このメソッドは、https://docs.python.org/2/library/doctestl#doctest.DocTestRunner [DocTestRunner]のサブクラスが出力をカスタマイズできるようにするために提供されています。直接呼び出すことはできません。

実行（テスト）

test（DocTestオブジェクト）の例を実行し、ライター関数_out_を使用して結果を表示します。

サマリ（[詳細]）

このDocTestRunnerによって実行されたすべてのテストケースの概要を出力し、named tuple TestResults（failed、attempted）を返します。オプションの_verbose_引数は、要約の詳細度を制御します。冗長性が指定されていない場合、DocTestRunnerの冗長性が使用されます。

OutputCheckerクラス

このクラスは、doctestの例からの実際の出力が期待される出力と一致するかどうかを確認するために使用されます。

次のメソッドは、このクラスで定義されています-

check_output（）

例からの実際の出力（got）が期待される出力（want）と一致する場合、 True を返します。これらの文字列は、同一の場合、常に一致すると見なされます。ただし、テストランナーが使用しているオプションフラグによっては、いくつかの非完全一致タイプも可能です。オプションフラグの詳細については、セクション_Option Flags_および_Directives_を参照してください。

output_difference（）

指定された例（example）の期待される出力と実際の出力（got）の違いを説明する文字列を返します。

UnittestとDocTestの統合

doctestモジュールは、doctestを含むモジュールおよびテキストファイルからユニットテストテストスイートを作成するために使用できる2つの関数を提供します。 unittestテスト検出と統合するには、テストモジュールにload_tests（）関数を含めます-

import unittest
import doctest
import doctestexample

def load_tests(loader, tests, ignore):
   tests.addTests(doctest.DocTestSuite(doctestexample))
   return tests

unittestとdoctestからのテストの結合されたTestSuiteが形成され、unittestモジュールのmain（）メソッドまたはrun（）メソッドによって実行できるようになりました。

以下は、doctestを使用してテキストファイルとモジュールから unittest.TestSuite インスタンスを作成するための2つの主な機能です-

doctest.DocFileSuite（）

doctestテストを1つ以上のテキストファイルから unittest.TestSuite に変換するために使用されます。返されるunittest.TestSuiteは、unittestフレームワークによって実行され、各ファイルでインタラクティブな例を実行します。ファイルの例のいずれかが失敗すると、合成された単体テストは失敗し、テストと（場合によっては）行番号を含むファイルの名前を示す failureException 例外が発生します。

doctest.DocTestSuite（）

モジュールのdoctestテストを unittest.TestSuite に変換するために使用されます。

返されるunittest.TestSuiteは、unittestフレームワークによって実行され、モジュール内の各doctestを実行します。 doctestのいずれかが失敗すると、合成された単体テストは失敗し、テストと（場合によっては）行番号を含むファイルの名前を示す failureException 例外が発生します

カバーの下で、DocTestSuite（）はdoctest.DocTestCaseインスタンスから unittest.TestSuite を作成し、DocTestCaseはunittest.TestCaseのサブクラスです。

同様に、DocFileSuite（）はdoctest.DocFileCaseインスタンスからunittest.TestSuiteを作成し、DocFileCaseはDocTestCaseのサブクラスです。

そのため、unittest.TestSuiteを作成する両方の方法でDocTestCaseのインスタンスが実行されます。 doctest関数を自分で実行する場合、オプションフラグをdoctest関数に渡すことにより、使用中のdoctestオプションを直接制御できます。

ただし、ユニットテストフレームワークを記述している場合、ユニットテストは最終的にテストをいつどのように実行するかを制御します。通常、フレームワークの作成者はdoctestレポートオプション（たとえば、コマンドラインオプションで指定される）を制御したいと考えていますが、unittestを介してdoctestテストランナーにオプションを渡す方法はありません。

Unittest-framework-doctest-api

目次