doctest Unittest API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2.4版本中的新功能。

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

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

注意

不像testmod()和DocTestFinder，ValueError如果模塊不包含文檔字符串，該函數(shù)會(huì)引發(fā)一個(gè)問(wèn)題。您可以通過(guò)傳遞一個(gè)DocTestFinder實(shí)例作為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測(cè)試轉(zhuǎn)換為一個(gè)模塊unittest.TestSuite。

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

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

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

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

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

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

2.3版本的新功能。

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

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

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

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

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

doctest.set_unittest_reportflags(flags)

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

參數(shù)標(biāo)志或一起選項(xiàng)標(biāo)志。請(qǐng)參見(jiàn)選項(xiàng)標(biāo)志部分。只能使用“報(bào)告標(biāo)志”。

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

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

New in version 2.4.