UnitTestフレームワーク-DoctestAPI

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

Example −期待される出力とペアになった単一の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（）メソッドを定義します。オブジェクトのdocstring、または含まれているオブジェクトのdocstringのいずれかによって定義されたDocTestのリストを返します。

DocTestParserクラス

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

get_doctest() −指定された文字列からすべてのdoctestの例を抽出し、それらを DocTest オブジェクト。
get_examples(string[, name]) −指定された文字列からすべてのdoctestの例を抽出し、それらをのリストとして返します Exampleオブジェクト。行番号は0から始まります。オプションの引数名は、この文字列を識別する名前であり、エラーメッセージにのみ使用されます。
parse(string[, name]) −与えられた文字列を例と間にあるテキストに分割し、それらを交互のリストとして返します Examplesと文字列。の行番号Examples0ベースです。オプションの引数名は、この文字列を識別する名前であり、エラーメッセージにのみ使用されます。

DocTestRunnerクラス

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

report_start（）

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

report_success（）

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

report_failure（）

与えられた例が失敗したことを報告します。このメソッドは、のサブクラスを許可するために提供されていますDocTestRunner出力をカスタマイズする。直接呼び出すべきではありません。

report_unexpected_exception（）

与えられた例が予期しない例外を引き起こしたことを報告してください。このメソッドは、DocTestRunnerのサブクラスが出力をカスタマイズできるようにするために提供されています。直接呼び出すべきではありません。

run（テスト）

test（DocTestオブジェクト）で例を実行し、writer関数outを使用して結果を表示します。

要約（[詳細]）

このDocTestRunnerによって実行されたすべてのテストケースの要約を出力し、名前付きタプルTestResults（失敗、試行）を返します。オプションのverbose引数は、要約の詳細度を制御します。詳細度が指定されていない場合は、DocTestRunnerの詳細度が使用されます。

OutputCheckerクラス

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

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

check_output（）

戻る True例からの実際の出力（got）が期待される出力（want）と一致する場合。これらの文字列は、同一である場合は常に一致すると見なされます。ただし、テストランナーが使用しているオプションフラグによっては、いくつかの不正確な一致タイプも考えられます。オプションフラグの詳細については、セクションオプションフラグとディレクティブを参照してください。

output_difference（）

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

DocTestとUnittestの統合

doctestモジュールは、モジュールとdoctestを含むテキストファイルから単体テストテストスイートを作成するために使用できる2つの関数を提供します。単体テストのテスト検出と統合するには、テストモジュールに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（）メソッドで実行できるようになります。

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

doctest.DocFileSuite（）

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

doctest.DocTestSuite（）

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

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

裏で、DocTestSuite（）は unittest.TestSuite doctest.DocTestCaseインスタンスのうち、DocTestCaseはunittest.TestCaseのサブクラスです。

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

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

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