doctest --- 測試交互性的Python示例?

哪些文件串被檢查了？?

模塊的文檔串以及所有函數(shù)、類和方法的文檔串都將被搜索。 導(dǎo)入模塊的對象不被搜索。

此外，如果 M.__test__ 存在并且 "為真值"，則它必須是一個字典，其中每個條目都將一個（字符串）名稱映射到一個函數(shù)對象、類對象或字符串。 從 M.__test__ 找到的函數(shù)和類對象的文檔字符串會被搜索，而字符串會被當作文檔字符串來處理。 在輸出時，每個鍵 K 在 M.__test__ 中都顯示為其名稱

<name of M>.__test__.K

任何發(fā)現(xiàn)的類都會以類似的方式進行遞歸搜索，以測試其包含的方法和嵌套類中的文檔串。

文檔串的例子是如何被識別的？?

在大多數(shù)情況下，對交互式控制臺會話的復(fù)制和粘貼功能工作得很好，但是 doctest 并不試圖對任何特定的 Python shell 進行精確的模擬。

>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
...     print("yes")
... else:
...     print("no")
...     print("NO")
...     print("NO!!!")
...
no
NO
NO!!!
>>>

任何預(yù)期的輸出必須緊隨包含代碼的最后 '>>> ' 或 '... ' 行，預(yù)期的輸出（如果有的話）延伸到下一 '>>> ' 行或全空白行。

fine輸出：

• 預(yù)期輸出不能包含一個全白的行，因為這樣的行被認為是預(yù)期輸出的結(jié)束信號。 如果預(yù)期的輸出包含一個空行，在你的測試例子中，在每一個預(yù)期有空行的地方加上``<BLANKLINE>``。

• 所有硬制表符都被擴展為空格，使用 8 列的制表符。由測試代碼生成的輸出中的制表符不會被修改。 因為樣本輸出中的任何硬制表符都會被擴展，這意味著如果代碼輸出包括硬制表符，文檔測試通過的唯一方法是 NORMALIZE_WHITESPACE 選項或者 指令 是有效的。 另外，測試可以被重寫，以捕獲輸出并將其與預(yù)期值進行比較，作為測試的一部分。這種對源碼中標簽的處理是通過試錯得出的，并被證明是最不容易出錯的處理方式。通過編寫一個自定義的 DocTestParser 類，可以使用一個不同的算法來處理標簽。

• 向stdout的輸出被捕獲，但不向stderr輸出（異?；厮萃ㄟ^不同的方式被捕獲）。

• 如果你在交互式會話中通過反斜線續(xù)行，或出于任何其他原因使用反斜線，你應(yīng)該使用原始文件串，它將完全保留你輸入的反斜線:

  >>>

  >>> def f(x):
  ...     r'''Backslashes in a raw docstring: m\n'''
  >>> print(f.__doc__)
  Backslashes in a raw docstring: m\n
  

  否則，反斜杠將被解釋為字符串的一部分。例如，上面的``n``會被解釋為一個換行符。 另外，你可以在doctest版本中把每個反斜杠加倍（而不使用原始字符串）:

  >>>

  >>> def f(x):
  ...     '''Backslashes in a raw docstring: m\\n'''
  >>> print(f.__doc__)
  Backslashes in a raw docstring: m\n
  

• 起始列并不重要:

  >>>

  >>> assert "Easy!"
        >>> import math
            >>> math.floor(1.9)
            1
  

  并從預(yù)期的輸出中剝離出與開始該例子的初始 '>>> ' 行中出現(xiàn)的同樣多的前導(dǎo)空白字符。

什么是執(zhí)行上下文？?

默認情況下，每次 doctest 找到要測試的文檔串時，它都會使用 M 的*淺層副本*，這樣運行測試就不會改變模塊的真正全局變量，而且 M 的一個測試也不會留下臨時變量，從而意外地讓另一個測試通過。這意味著例子可以自由地使用 M 中的任何頂級定義的名字，以及正在運行的文檔串中早期定義的名字。用例不能看到其他文檔串中定義的名字。

你可以通過將``globs=your_dict``傳遞給 testmod() 或 testfile() 來強制使用你自己的dict作為執(zhí)行環(huán)境。

異常如何處理？?

沒問題，只要回溯是這個例子產(chǎn)生的唯一輸出：只要粘貼回溯即可。1 由于回溯所包含的細節(jié)可能會迅速變化（例如，確切的文件路徑和行號），這是doctest努力使其接受的內(nèi)容具有靈活性的一種情況。

簡單實例:

>>> [1, 2, 3].remove(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: list.remove(x): x not in list

如果 ValueError 被觸發(fā)，該測試就會成功，list.remove(x): x not in list 的細節(jié)如圖所示。

異常的預(yù)期輸出必須以回溯頭開始，可以是以下兩行中的任何一行，縮進程度與例子中的第一行相同:

Traceback (most recent call last):
Traceback (innermost last):

回溯頭的后面是一個可選的回溯堆棧，其內(nèi)容被doctest忽略。 回溯堆棧通常是省略的，或者從交互式會話中逐字復(fù)制的。

回溯堆棧的后面是最有用的部分：包含異常類型和細節(jié)的一行（幾行）。 這通常是回溯的最后一行，但如果異常有多行細節(jié)，則可以延伸到多行:

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: multi
    line
detail

最后三行（以 ValueError 開頭）將與異常的類型和細節(jié)進行比較，其余的被忽略。

最佳實踐是省略回溯棧，除非它為這個例子增加了重要的文檔價值。 因此，最后一個例子可能更好，因為:

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
    ...
ValueError: multi
    line
detail

請注意，回溯的處理方式非常特別。 特別是，在重寫的例子中，... 的使用與 doctest 的 ELLIPSIS 選項無關(guān)。 該例子中的省略號可以不寫，也可以是三個（或三百個）逗號或數(shù)字，或者是一個縮進的 Monty Python 短劇的劇本。

有些細節(jié)你應(yīng)該讀一遍，但不需要記住：

• Doctest 不能猜測你的預(yù)期輸出是來自異?；厮葸€是來自普通打印。 因此，例如，一個期望 ValueError: 42 is prime 的用例將通過測試，無論 ValueError 是真的被觸發(fā)，或者該用例只是打印了該回溯文本。 在實踐中，普通輸出很少以回溯標題行開始，所以這不會產(chǎn)生真正的問題。

• 回溯堆棧的每一行（如果有的話）必須比例子的第一行縮進， 或者 以一個非字母數(shù)字的字符開始?；厮蓊^之后的第一行縮進程度相同，并且以字母數(shù)字開始，被認為是異常細節(jié)的開始。當然，這對真正的回溯來說是正確的事情。

• 當 IGNORE_EXCEPTION_DETAIL doctest 選項被指定時，最左邊的冒號后面的所有內(nèi)容以及異常名稱中的任何模塊信息都被忽略。

• 交互式 shell 省略了一些 SyntaxError 的回溯頭行。但 doctest 使用回溯頭行來區(qū)分異常和非異常。所以在罕見的情況下，如果你需要測試一個省略了回溯頭的 SyntaxError，你將需要手動添加回溯頭行到你的測試用例中。

• For some exceptions, Python displays the position of the error using ^ markers and tildes:

  >>>

  >>> 1 + None
    File "<stdin>", line 1
      1 + None
      ~~^~~~~~
  TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
  

  由于顯示錯誤位置的行在異常類型和細節(jié)之前，它們不被doctest檢查。 例如，下面的測試會通過，盡管它把``^``標記放在了錯誤的位置:

  >>>

  >>> 1 + None
    File "<stdin>", line 1
      1 + None
      ^~~~~~~~
  TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
  

選項標記?

一系列選項旗標控制著 doctest 的各方面行為。 旗標的符號名稱以模塊常量的形式提供，可以一起 bitwise ORed 并傳遞給各種函數(shù)。 這些名稱也可以在 doctest directives 中使用，并且可以通過 -o 選項傳遞給 doctest 命令行接口。

第一組選項定義了測試語義，控制doctest如何決定實際輸出是否與用例的預(yù)期輸出相匹配方面的問題。

doctest.DONT_ACCEPT_TRUE_FOR_1?

默認情況下，如果一個預(yù)期的輸出塊只包含 1，那么實際的輸出塊只包含 1 或只包含 True 就被認為是匹配的，同樣，0 與 False 也是如此。 當 DONT_ACCEPT_TRUE_FOR_1 被指定時，兩種替換都不允許。 默認行為是為了適應(yīng) Python 將許多函數(shù)的返回類型從整數(shù)改為布爾值；期望 "小整數(shù)" 輸出的測試在這些情況下仍然有效。 這個選項可能會消失，但不會在幾年內(nèi)消失。

doctest.DONT_ACCEPT_BLANKLINE?

默認情況下，如果一個預(yù)期輸出塊包含一個只包含字符串 <BLANKLINE> 的行，那么該行將與實際輸出中的一個空行相匹配。 因為一個真正的空行是對預(yù)期輸出的限定，這是傳達預(yù)期空行的唯一方法。 當 DONT_ACCEPT_BLANKLINE 被指定時，這種替換是不允許的。

doctest.NORMALIZE_WHITESPACE?

當指定時，所有的空白序列（空白和換行）都被視為相等。預(yù)期輸出中的任何空白序列將與實際輸出中的任何空白序列匹配。默認情況下，空白必須完全匹配。 NORMALIZE_WHITESPACE 在預(yù)期輸出非常長的一行，而你想把它包在源代碼的多行中時特別有用。

doctest.ELLIPSIS?

當指定時，預(yù)期輸出中的省略號（...）可以匹配實際輸出中的任何子串。這包括跨行的子串和空子串，所以最好保持簡單的用法。復(fù)雜的用法會導(dǎo)致與``.*``在正則表達式中容易出現(xiàn)的 "oops, it matched too much!"相同的意外情況。

doctest.IGNORE_EXCEPTION_DETAIL?

When specified, doctests expecting exceptions pass so long as an exception of the expected type is raised, even if the details (message and fully-qualified exception name) don't match.

For example, an example expecting ValueError: 42 will pass if the actual exception raised is ValueError: 3*14, but will fail if, say, a TypeError is raised instead. It will also ignore any fully-qualified name included before the exception class, which can vary between implementations and versions of Python and the code/libraries in use. Hence, all three of these variations will work with the flag specified:

>>>

>>> raise Exception('message')
Traceback (most recent call last):
Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
builtins.Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
__main__.Exception: message

Note that ELLIPSIS can also be used to ignore the details of the exception message, but such a test may still fail based on whether the module name is present or matches exactly.

在 3.2 版更改: IGNORE_EXCEPTION_DETAIL 現(xiàn)在也忽略了與包含被測異常的模塊有關(guān)的任何信息。

doctest.SKIP?

當指定時，完全不運行這個用例。 這在doctest用例既是文檔又是測試案例的情況下很有用，一個例子應(yīng)該包括在文檔中，但不應(yīng)該被檢查。例如，這個例子的輸出可能是隨機的；或者這個例子可能依賴于測試驅(qū)動程序所不能使用的資源。

SKIP標志也可用于臨時 "注釋" 用例。

doctest.COMPARISON_FLAGS?

一個比特或運算將上述所有的比較標志放在一起。

第二組選項控制測試失敗的報告方式：

doctest.REPORT_UDIFF?

當指定時，涉及多行預(yù)期和實際輸出的故障將使用統(tǒng)一的差異來顯示。

doctest.REPORT_CDIFF?

當指定時，涉及多行預(yù)期和實際輸出的故障將使用上下文差異來顯示。

doctest.REPORT_NDIFF?

當指定時，差異由``difflib.Differ``來計算，使用與流行的:file:ndiff.py`工具相同的算法。這是唯一一種標記行內(nèi)和行間差異的方法。 例如，如果一行預(yù)期輸出包含數(shù)字``1`，而實際輸出包含字母``l``，那么就會插入一行，用圓點標記不匹配的列位置。

doctest.REPORT_ONLY_FIRST_FAILURE?

當指定時，在每個 doctest 中顯示第一個失敗的用例，但隱藏所有其余用例的輸出。 這將防止 doctest 報告由于先前的失敗而中斷的正確用例；但也可能隱藏獨立于第一個失敗的不正確用例。 當 REPORT_ONLY_FIRST_FAILURE 被指定時，其余的用例仍然被運行，并且仍然計入報告的失敗總數(shù)；只是輸出被隱藏了。

doctest.FAIL_FAST?

當指定時，在第一個失敗的用例后退出，不嘗試運行其余的用例。因此，報告的失敗次數(shù)最多為1。這個標志在調(diào)試時可能很有用，因為第一個失敗后的用例甚至不會產(chǎn)生調(diào)試輸出。

doctest命令行接受選項``-f``作為``-o FAIL_FAST``的簡潔形式。

3.4 新版功能.

doctest.REPORTING_FLAGS?

一個比特或操作將上述所有的報告標志組合在一起。

還有一種方法可以注冊新的選項標志名稱，不過這并不有用，除非你打算通過子類來擴展 doctest 內(nèi)部。

doctest.register_optionflag(name)?

用給定的名稱創(chuàng)建一個新的選項標志，并返回新標志的整數(shù)值。 register_optionflag() 可以在繼承 OutputChecker 或 DocTestRunner 時使用，以創(chuàng)建子類支持的新選項。 register_optionflag() 應(yīng)始終使用以下方式調(diào)用:

MY_FLAG = register_optionflag('MY_FLAG')

指令?

Doctest指令可以用來修改單個例子的 option flags 。 Doctest指令是在一個用例的源代碼后面的特殊Python注釋。

directive             ::=  "#" "doctest:" directive_options
directive_options     ::=  directive_option ("," directive_option)\*
directive_option      ::=  on_or_off directive_option_name
on_or_off             ::=  "+" \| "-"
directive_option_name ::=  "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ...

+ 或 - 與指令選項名稱之間不允許有空格。 指令選項名稱可以是上面解釋的任何一個選項標志名稱。

一個用例的 doctest 指令可以修改 doctest 對該用例的行為。 使用 + 來啟用指定的行為，或者使用 - 來禁用它。

For example, this test passes:

>>> print(list(range(20)))  # doctest: +NORMALIZE_WHITESPACE
[0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
10,  11, 12, 13, 14, 15, 16, 17, 18, 19]

Without the directive it would fail, both because the actual output doesn't have two blanks before the single-digit list elements, and because the actual output is on a single line. This test also passes, and also requires a directive to do so:

>>> print(list(range(20)))  # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]

Multiple directives can be used on a single physical line, separated by commas:

>>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]

If multiple directive comments are used for a single example, then they are combined:

>>> print(list(range(20)))  # doctest: +ELLIPSIS
...                         # doctest: +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]

As the previous example shows, you can add ... lines to your example containing only directives. This can be useful when an example is too long for a directive to comfortably fit on the same line:

>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
... # doctest: +ELLIPSIS
[0, ..., 4, 10, ..., 19, 30, ..., 39]

請注意，由于所有的選項都是默認禁用的，而指令只適用于它們出現(xiàn)的用例，所以啟用選項 (通過指令中的 +) 通常是唯一有意義的選擇。 然而，選項標志也可以被傳遞給運行測試的函數(shù)，建立不同的默認值。 在這種情況下，通過指令中的 - 來禁用一個選項可能是有用的。

警告?

doctest 是嚴格地要求在預(yù)期輸出中完全匹配。 如果哪怕只有一個字符不匹配，測試就會失敗。 這可能會讓你吃驚幾次，在你確切地了解到 Python 對輸出的保證和不保證之前。 例如，當打印一個集合時，Python 不保證元素以任何特定的順序被打印出來，所以像:

>>> foo()
{"Hermione", "Harry"}

是不可靠的！一個變通方法是用:

>>> foo() == {"Hermione", "Harry"}
True

來取代。另一個是使用

>>> d = sorted(foo())
>>> d
['Harry', 'Hermione']

還有其他的問題，但你會明白的。

Another bad idea is to print things that embed an object address, like

>>> id(1.0)  # certain to fail some of the time  
7948648
>>> class C: pass
>>> C()  # the default repr() for instances embeds an address   
<C object at 0x00AC18F0>

The ELLIPSIS directive gives a nice approach for the last example:

>>> C()  # doctest: +ELLIPSIS
<C object at 0x...>

浮點數(shù)在不同的平臺上也會有小的輸出變化，因為Python在浮點數(shù)的格式化上依賴于平臺的C庫，而C庫在這個問題上的質(zhì)量差異很大。:

>>> 1./7  # risky
0.14285714285714285
>>> print(1./7) # safer
0.142857142857
>>> print(round(1./7, 6)) # much safer
0.142857

形式``I/2.**J``的數(shù)字在所有的平臺上都是安全的，我經(jīng)常設(shè)計一些測試的用例來產(chǎn)生該形式的數(shù):

>>> 3./4  # utterly safe
0.75

簡單的分數(shù)也更容易讓人理解，這也使得文件更加完善。

DocTest 對象?

class doctest.DocTest(examples, globs, name, filename, lineno, docstring)?

應(yīng)該在單一命名空間中運行的doctest用例的集合。構(gòu)造函數(shù)參數(shù)被用來初始化相同名稱的屬性。

DocTest 定義了以下屬性。 它們由構(gòu)造函數(shù)初始化，不應(yīng)該被直接修改。

examples?

一個 Example 對象的列表，它編碼了應(yīng)該由該測試運行的單個交互式 Python 用例。

globs?

例子應(yīng)該運行的命名空間（又稱 globals ）。這是一個將名字映射到數(shù)值的字典。例子對名字空間的任何改變（比如綁定新的變量）將在測試運行后反映在 globs 中。

name?

識別 DocTest 的字符串名稱。 通常情況下，這是從測試中提取的對象或文件的名稱。

filename?

這個 DocTest 被提取的文件名；或者為``None``，如果文件名未知，或者 DocTest 沒有從文件中提取。

lineno?

filename 中的行號，這個 DocTest 開始的地方，或者行號不可用時為``None``。 這個行號相對于文件的開頭來說是零的。

docstring?

從測試中提取的字符串，或者如果字符串不可用，或者為 None ，如果測試沒有從字符串中提取。

Example 對象?

class doctest.Example(source, want, exc_msg=None, lineno=0, indent=0, options=None)?

單個交互式用例，由一個 Python 語句及其預(yù)期輸出組成。 構(gòu)造函數(shù)參數(shù)被用來初始化相同名稱的屬性。

Example 定義了以下屬性。 它們由構(gòu)造函數(shù)初始化，不應(yīng)該被直接修改。

source?

一個包含該用例源碼的字符串。 源碼由一個 Python 語句組成，并且總是以換行結(jié)束；構(gòu)造函數(shù)在必要時添加一個換行。

want?

運行這個用例的源碼的預(yù)期輸出（可以是 stdout ，也可以是異常情況下的回溯）。 want 以一個換行符結(jié)束，除非沒有預(yù)期的輸出，在這種情況下它是一個空字符串。 構(gòu)造函數(shù)在必要時添加一個換行。

exc_msg?

用例產(chǎn)生的異常信息，如果這個例子被期望產(chǎn)生一個異常；或者為 None ，如果它不被期望產(chǎn)生一個異常。 這個異常信息與 traceback.format_exception_only() 的返回值進行比較。 exc_msg 以換行結(jié)束，除非是 None 。

lineno?

包含本例的字符串中的行號，即本例的開始。 這個行號相對于包含字符串的開頭來說是以零開始的。

indent?

用例在包含字符串中的縮進，即在用例的第一個提示前有多少個空格字符。

options?

一個從選項標志到 True 或 False 的字典映射，用于覆蓋這個例子的默認選項。 任何不包含在這個字典中的選項標志都被保留為默認值（由 DocTestRunner 的 optionflags 指定）。默認情況下，沒有選項被設(shè)置。

DocTestFinder 對象?

class doctest.DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)?

一個處理類，用于從一個給定的對象的 docstring 和其包含的對象的 docstring 中提取與之相關(guān)的 DocTest 。 DocTest 可以從模塊、類、函數(shù)、方法、靜態(tài)方法、類方法和屬性中提取。

可選的參數(shù) verbose 可以用來顯示查找器搜索到的對象。 它的默認值是 False （無輸出）。

可選的參數(shù) parser 指定了 DocTestParser 對象（或一個可替換的對象），用于從文檔串中提取 doctest 。

如果可選的參數(shù) recurse 是 False ，那么 DocTestFinder.find() 將只檢查給定的對象，而不是任何包含的對象。

如果可選參數(shù) exclude_empty 為 False ，那么 DocTestFinder.find() 將包括對文檔字符串為空的對象的測試。

DocTestFinder 定義了以下方法：

find(obj[, name][, module][, globs][, extraglobs])?

返回 DocTest 的列表，該列表由 obj 的文檔串或其包含的任何對象的文檔串定義。

可選參數(shù) name 指定了對象的名稱；這個名稱將被用來為返回的 DocTest 構(gòu)建名稱。 如果沒有指定*name*，則使用 obj.__name__ 。

可選參數(shù) module 是包含給定對象的模塊。如果沒有指定模塊或者是 None ，那么測試查找器將試圖自動確定正確的模塊。 該對象被使用的模塊：

• 作為一個默認的命名空間，如果沒有指定 globs 。

• 為了防止 DocTestFinder 從其他模塊導(dǎo)入的對象中提取 DocTest 。 (包含有除 module 以外的模塊的對象會被忽略)。

• 找到包含該對象的文件名。

• 找到該對象在其文件中的行號。

如果 module 是 False ，將不會試圖找到這個模塊。 這是不明確的，主要用于測試 doctest 本身：如果 module 是 False ，或者是 None 但不能自動找到，那么所有對象都被認為屬于（不存在的）模塊，所以所有包含的對象將（遞歸地）被搜索到 doctest 。

每個 DocTest 的 globals 是由 globs 和 extraglobs 組合而成的（ extraglobs 的綁定覆蓋 globs 的綁定）。 為每個 DocTest 創(chuàng)建一個新的 globals 字典的淺層拷貝。如果沒有指定 globs ，那么它默認為模塊的 __dict__ ，如果指定了或者為 {} ，則除外。 如果沒有指定 extraglobs ，那么它默認為 {} 。

DocTestParser 對象?

class doctest.DocTestParser?

一個處理類，用于從一個字符串中提取交互式的用例，并使用它們來創(chuàng)建一個 DocTest 對象。

DocTestParser 定義了以下方法：

get_doctest(string, globs, name, filename, lineno)?

從給定的字符串中提取所有的測試用例，并將它們收集到一個 DocTest 對象中。

globs 、 name 、 filename 和 lineno 是新的 DocTest 對象的屬性。 更多信息請參見 DocTest 的文檔。

get_examples(string, name='<string>')?

從給定的字符串中提取所有的測試用例，并以 Example 對象列表的形式返回。 行數(shù)以 0 為基數(shù)。 可選參數(shù) name 用于識別這個字符串的名稱，只用于錯誤信息。

parse(string, name='<string>')?

將給定的字符串分成用例和中間的文本，并以 Example 和字符串交替的列表形式返回。 Example 的行號以 0 為基數(shù)。 可選參數(shù) name 用于識別這個字符串的名稱，只用于錯誤信息。

DocTestRunner 對象?

class doctest.DocTestRunner(checker=None, verbose=None, optionflags=0)?

一個處理類，用于執(zhí)行和驗證 DocTest 中的交互式用例。

預(yù)期輸出和實際輸出之間的比較是由一個 OutputChecker 完成的。 這種比較可以用一些選項標志來定制；更多信息請看 選項標記 部分。 如果選項標志不夠，那么也可以通過向構(gòu)造函數(shù)傳遞 OutputChecker 的子類來定制比較。

測試運行器的顯示輸出可以通過兩種方式控制。首先，一個輸出函數(shù)可以被傳遞給 TestRunner.run() ；這個函數(shù)將被調(diào)用，并顯示出應(yīng)該顯示的字符串。 它的默認值是 sys.stdout.write 。 如果捕獲輸出是不夠的，那么也可以通過子類化 DocTestRunner 來定制顯示輸出，并重寫 report_start() , report_success() , report_unexpected_exception() 和 report_failure() 方法。

可選的關(guān)鍵字參數(shù) checker 指定了 OutputChecker 對象（或其相似替換），它應(yīng)該被用來比較預(yù)期輸出和 doctest 用例的實際輸出。

可選的關(guān)鍵字參數(shù) verbose 控制 DocTestRunner 的詳細程度。 如果 verbose 是 True ，那么每個用例的信息都會被打印出來，當它正在運行時。 如果 verbose 是 False ，則只打印失敗的信息。 當 verbose 沒有指定，或者為 None ，如果使用了命令行開關(guān) -v ，則使用verbose輸出。

可選的關(guān)鍵字參數(shù) optionflags 可以用來控制測試運行器如何比較預(yù)期輸出和實際輸出，以及如何顯示失敗。更多信息，請參見章節(jié) 選項標記 。

DocTestParser 定義了以下方法：

report_start(out, test, example)?

報告測試運行器即將處理給定的用例。提供這個方法是為了讓 DocTestRunner 的子類能夠定制他們的輸出；它不應(yīng)該被直接調(diào)用。

example 是即將被處理的用。 test 是 包含用例 的測試。 out 是傳遞給 DocTestRunner.run() 的輸出函數(shù)。

report_success(out, test, example, got)?

報告給定的用例運行成功。 提供這個方法是為了讓 DocTestRunner 的子類能夠定制他們的輸出；它不應(yīng)該被直接調(diào)用。

example 是即將被處理的用例。 got 是這個例子的實際輸出。 test 是包含 example 的測試。 out 是傳遞給 DocTestRunner.run() 的輸出函數(shù)。

report_failure(out, test, example, got)?

報告給定的用例運行失敗。 提供這個方法是為了讓 DocTestRunner 的子類能夠定制他們的輸出；它不應(yīng)該被直接調(diào)用。

example 是即將被處理的用例。 got 是這個例子的實際輸出。 test 是包含 example 的測試。 out 是傳遞給 DocTestRunner.run() 的輸出函數(shù)。

report_unexpected_exception(out, test, example, exc_info)?

報告給定的用例觸發(fā)了一個異常。 提供這個方法是為了讓 DocTestRunner 的子類能夠定制他們的輸出；它不應(yīng)該被直接調(diào)用。

example 是將要被處理的用例。 exc_info 是一個元組，包含關(guān)于異常的信息（如由 sys.exc_info() 返回）。 test 是包含 example 的測試。 out 是傳遞給 DocTestRunner.run() 的輸出函數(shù)。

run(test, compileflags=None, out=None, clear_globs=True)?

在 test （一個 DocTest 對象）中運行這些用例，并使用寫入函數(shù) out 顯示結(jié)果。

這些用例都是在命名空間 test.globs 中運行的。 如果 clear_globs 為 True （默認），那么這個命名空間將在測試運行后被清除，以幫助進行垃圾回收。如果你想在測試完成后檢查命名空間，那么使用 clear_globs=False 。

compileflags 給出了 Python 編譯器在運行例子時應(yīng)該使用的標志集。如果沒有指定，那么它將默認為適用于 globs 的 future-import 標志集。

每個用例的輸出都使用 DocTestRunner 的輸出檢查器進行檢查，結(jié)果由 DocTestRunner.report_*() 方法進行格式化。

summarize(verbose=None)?

打印這個 DocTestRunner 運行過的所有測試用例的摘要，并返回一個 named tuple TestResults(failed, attempted) 。

可選的 verbose 參數(shù)控制摘要的詳細程度。 如果沒有指定 verbose ，那么將使用 DocTestRunner 的 verbose 。

OutputChecker 對象?

class doctest.OutputChecker?

一個用于檢查測試用例的實際輸出是否與預(yù)期輸出相匹配的類。 OutputChecker 定義了兩個方法： check_output() ，比較給定的一對輸出，如果它們匹配則返回 True ； output_difference() ，返回一個描述兩個輸出之間差異的字符串。

OutputChecker 定義了以下方法：

check_output(want, got, optionflags)?

如果一個用例的實際輸出（ got ）與預(yù)期輸出（ want ）匹配，則返回 True 。 如果這些字符串是相同的，總是被認為是匹配的；但是根據(jù)測試運行器使用的選項標志，也可能有幾種非精確的匹配類型。 參見章節(jié) 選項標記 了解更多關(guān)于選項標志的信息。

output_difference(example, got, optionflags)?

返回一個字符串，描述給定用例（ example ）的預(yù)期輸出和實際輸出（ got ）之間的差異。 optionflags 是用于比較 want 和 got 的選項標志集。