隨著您的文檔測試模塊集合的增長，您需要一種系統(tǒng)地運行所有文檔測試的方法。在Python 2.4之前，doctest有一個幾乎沒有文檔記錄的Tester類，它提供了一個基本方法來組合多個模塊的doctests。Tester是虛弱的，實際上最嚴(yán)重的Python測試框架建立在unittest模塊上，它提供了許多靈活的方法來結(jié)合多個來源的測試。所以，在Python 2.4，doctest的Tester類已被棄用，doctest提供了可用于創(chuàng)建兩個函數(shù)unittest從模塊和包含文檔測試的文本文件的測試套件。要與unittest測試發(fā)現(xiàn)集成，load_tests()在您的測試模塊中包含一個函數(shù)：

import unittest
import doctest
import my_module_with_doctests

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

有兩個主要的功能可以用unittest.TestSuite文本文件和模塊創(chuàng)建實例：

doctest.DocFileSuite(*paths, [module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding])

將doctest測試從一個或多個文本文件轉(zhuǎn)換為unittest.TestSuite。

返回的unittest.TestSuite內(nèi)容將由unittest框架運行并在每個文件中運行交互式示例。如果任何文件中的示例失敗，則合成的單元測試將失敗，并failureException引發(fā)異常，顯示包含測試的文件的名稱和一個（有時是近似的）行號。

將一個或多個路徑（字符串）傳遞給要檢查的文本文件。

選項可以作為關(guān)鍵字參數(shù)提供：

可選參數(shù)module_relative指定應(yīng)如何解釋路徑中的文件名：

• 如果module_relative是True（缺省值），則路徑中的每個文件名指定與操作系統(tǒng)無關(guān)的模塊相對路徑。默認(rèn)情況下，這個路徑是相對于調(diào)用模塊的目錄; 但是如果指定了package參數(shù)，那么它與該包相關(guān)。為確保操作系統(tǒng)無關(guān)性，每個文件名應(yīng)使用/字符來分隔路徑段，并且可能不是絕對路徑（即可能不以其開頭/）。

• 如果module_relative是False，則路徑中的每個文件名都指定一個OS特定的路徑。路徑可以是絕對的或相對的; 相對路徑相對于當(dāng)前工作目錄被解析。

可選參數(shù)包是Python包或Python包的名稱，其目錄應(yīng)該用作路徑中與模塊相關(guān)的文件名的基本目錄。如果未指定包，則調(diào)用模塊的目錄將用作模塊相關(guān)文件名的基本目錄。如果module_relative是指定包，那是False錯誤的。

可選參數(shù)setUp指定測試套件的設(shè)置函數(shù)。這在每個文件中運行測試之前被調(diào)用。該的setUp函數(shù)將被傳遞一個DocTest對象。setUp函數(shù)可以在測試的globs屬性通過時訪問測試全局變量。

可選參數(shù)tearDown指定測試套件的拆卸函數(shù)。這是在每個文件中運行測試后調(diào)用的。在拆卸會被傳遞給一個DocTest對象。setUp函數(shù)可以在測試的globs屬性通過時訪問測試全局變量。

可選參數(shù)globs是包含測試的初始全局變量的字典。每個測試都會創(chuàng)建一本新字典。默認(rèn)情況下，globs是一個新的空字典。

可選參數(shù)optionflags指定測試的默認(rèn)doctest選項，由各個選項標(biāo)記組合或創(chuàng)建。請參見選項標(biāo)志部分。請參閱set_unittest_reportflags()下面的功能以更好地設(shè)置報告選項。

可選參數(shù)解析器指定DocTestParser應(yīng)該用于從文件中提取測試的一個（或子類）。它默認(rèn)為一個普通的解析器（即，DocTestParser()）。

可選的參數(shù)編碼指定應(yīng)該用于將文件轉(zhuǎn)換為unicode的編碼。

2.4版本中的新功能。

在版本2.5中進行了更改：將全局__file__添加到提供給使用文本文件加載的文檔測試的全局文件中DocFileSuite()。

在版本2.5中更改：添加了參數(shù)編碼。

注意

不像testmod()和DocTestFinder，ValueError如果模塊不包含文檔字符串，該函數(shù)會引發(fā)一個問題。您可以通過傳遞一個DocTestFinder實例作為test_finder參數(shù)，并將其exclude_empty關(guān)鍵字參數(shù)設(shè)置為False：

>>> finder = doctest.DocTestFinder(exclude_empty=False)
>>> suite = doctest.DocTestSuite(test_finder=finder)

doctest.DocTestSuite([module][, globs][, extraglobs][, test_finder][, setUp][, tearDown][, checker])

將模塊的doctest測試轉(zhuǎn)換為一個模塊unittest.TestSuite。

返回的unittest.TestSuite是由unittest框架運行并在模塊中運行每個doctest。如果有任何文檔測試失敗，則合成的單元測試失敗，并failureException引發(fā)異常，顯示包含測試的文件的名稱和一個（有時是近似的）行號。

可選參數(shù)模塊提供要測試的模塊。它可以是一個模塊對象或一個（可能點綴的）模塊名稱。如果未指定，則使用調(diào)用此函數(shù)的模塊。

可選參數(shù)globs是包含測試的初始全局變量的字典。每個測試都會創(chuàng)建一本新字典。默認(rèn)情況下，globs是一個新的空字典。

可選參數(shù)extraglobs指定一組額外的全局變量，這是合并成的水珠。默認(rèn)情況下，不使用額外的全局變量。

可選參數(shù)test_finder是DocTestFinder用于從模塊中提取doctests 的對象（或插入替換）。

可選參數(shù)setUp，tearDown和optionflags與DocFileSuite()上面的函數(shù)相同。

2.3版本的新功能。

在版本2.4中更改：添加了參數(shù)globs，extraglobs，test_finder，setUp，tearDown和optionflags ; 這個功能現(xiàn)在使用和。一樣的搜索技術(shù)testmod()。

在幕后，DocTestSuite()創(chuàng)建unittest.TestSuite出的doctest.DocTestCase實例，DocTestCase是的子類unittest.TestCase。DocTestCase這里沒有記錄（這是一個內(nèi)部細節(jié)），但是研究它的代碼可以回答關(guān)于unittest集成確切細節(jié)的問題。

同樣，DocFileSuite()創(chuàng)建unittest.TestSuite出的doctest.DocFileCase實例，DocFileCase是的子類DocTestCase。

因此創(chuàng)建unittest.TestSuite運行實例的兩種方式DocTestCase。這對于一個微妙的原因很重要：當(dāng)你doctest自己運行函數(shù)時，可以doctest通過將選項標(biāo)志傳遞給doctest函數(shù)來直接控制正在使用的選項。但是，如果你正在編寫一個unittest框架，unittest最終控制何時以及如何運行測試?？蚣茏髡咄ǔＯＭ刂芼octest報表選項（可能例如由命令行選項指定），但是沒有辦法將選項傳遞unittest給doctest測試運行者。

出于這個原因，doctest還支持通過此功能支持doctest特定于unittest支持的報告標(biāo)志的概念：

doctest.set_unittest_reportflags(flags)

設(shè)置doctest要使用的報告標(biāo)志。

參數(shù)標(biāo)志或一起選項標(biāo)志。請參見選項標(biāo)志部分。只能使用“報告標(biāo)志”。

這是一個模塊全局設(shè)置，并影響模塊運行的所有將來的doctests unittest：在DocTestCase實例構(gòu)建時查看為測試用例指定的選項標(biāo)記DocTestCase的runTest()方法。如果沒有指定報告的標(biāo)志（這是典型的和預(yù)期的情況下），doctest的unittest報告標(biāo)志是按位或運算進入選項標(biāo)志，因此增強選項標(biāo)志傳遞給創(chuàng)建運行文檔測試DocTestRunner實例。如果時指定的任何報告的標(biāo)志例如構(gòu)建DocTestCase，doctest的unittest報告標(biāo)志被忽略。

在函數(shù)被調(diào)用之前生效的報告標(biāo)志的值由函數(shù)返回unittest。

New in version 2.4.