單元測試框架 - Doctest API

doctest API圍繞以下兩個用於儲存文件字串中互動式示例的容器類展開：

示例 - 單個 Python 語句及其預期輸出。
DocTest - 示例的集合，通常是從單個文件字串或文字檔案中提取的。

定義了以下附加處理類來查詢、解析、執行和檢查 doctest 示例：

DocTestFinder - 查詢給定模組中的所有文件字串，並使用 DocTestParser 從包含互動式示例的每個文件字串建立 DocTest。
DocTestParser - 從字串（例如物件的文件字串）建立 doctest 物件。
DocTestRunner - 執行 doctest 中的示例，並使用 OutputChecker 驗證其輸出。
OutputChecker - 將 doctest 示例的實際輸出與預期輸出進行比較，並確定它們是否匹配。

DocTestFinder 類

這是一個處理類，用於從其文件字串及其包含物件的文件字串中提取與給定物件相關的 doctest。目前可以從以下物件型別中提取 Doctest：模組、函式、類、方法、靜態方法、類方法和屬性。

此類定義了 find() 方法。它返回由物件的文件字串或其任何包含物件的文件字串定義的 DocTest 列表。

DocTestParser 類

這是一個處理類，用於從字串中提取互動式示例，並使用它們來建立 DocTest 物件。此類定義了以下方法：

get_doctest() - 從給定字串中提取所有 doctest 示例，並將它們收集到一個DocTest物件中。
get_examples(string[, name]) - 從給定字串中提取所有 doctest 示例，並將它們作為Example物件的列表返回。行號為基於 0 的。可選引數 name 是標識此字串的名稱，僅用於錯誤訊息。
parse(string[, name]) - 將給定字串劃分為示例和中間文字，並將它們作為交替的Examples和字串的列表返回。Examples的行號為基於 0 的。可選引數 name 是標識此字串的名稱，僅用於錯誤訊息。

DocTestRunner 類

這是一個處理類，用於執行和驗證 DocTest 中的互動式示例。其中定義了以下方法：

report_start()

報告測試執行器即將處理給定示例。提供此方法是為了允許DocTestRunner的子類自定義其輸出；不應直接呼叫它。

report_success()

報告給定示例已成功執行。提供此方法是為了允許 DocTestRunner 的子類自定義其輸出；不應直接呼叫它。

report_failure()

報告給定示例失敗。提供此方法是為了允許DocTestRunner的子類自定義其輸出；不應直接呼叫它。

report_unexpected_exception()

報告給定示例引發了意外異常。提供此方法是為了允許DocTestRunner的子類自定義其輸出；不應直接呼叫它。

run(test)

執行test（DocTest 物件）中的示例，並使用 writer 函式out顯示結果。

summarize([verbose])

列印此 DocTestRunner 已執行的所有測試用例的摘要，並返回一個命名元組TestResults(failed, attempted)。可選的verbose引數控制摘要的詳細程度。如果未指定詳細程度，則使用 DocTestRunner 的詳細程度。

OutputChecker 類

此類用於檢查 doctest 示例的實際輸出是否與預期輸出匹配。

此類中定義了以下方法：

check_output()

如果示例的實際輸出（got）與預期輸出（want）匹配，則返回True。如果這些字串完全相同，則始終認為它們匹配；但根據測試執行器使用的選項標誌，還可能允許幾種非精確匹配型別。有關選項標誌的更多資訊，請參閱選項標誌和指令部分。

output_difference()

返回一個字串，描述給定示例（example）的預期輸出和實際輸出（got）之間的差異。

DocTest 與 Unittest 的整合

doctest 模組提供兩個函式，可用於從包含 doctest 的模組和文字檔案建立 unittest 測試套件。要與 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例項的兩個主要函式：

doctest.DocFileSuite()

它用於將一個或多個文字檔案的 doctest 測試轉換為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 選項。

但是，如果您正在編寫 unittest 框架，unittest 最終會控制測試何時以及如何執行。框架作者通常希望控制 doctest 報告選項（例如，由命令列選項指定），但是沒有辦法透過 unittest 將選項傳遞給 doctest 測試執行器。

列印頁面