Python doctest模块：文档测试（超级详细）

前面章节不止一次讲到，Python 支持给函数、类以及类方法添加说明性文档，并提供 help() 函数和 __doc__ 属性获取指定成员的说明文档。例如：

def display(add):
    '''
    这是一个函数

    '''
    print(add)
   
class my_cla:
    '''
    这是一个类

    '''
    def say(self,add):
        '''
        这是一个类实例方法
        '''
        print(add)
help(display)

程序输出结果为：

Help on function display in module __main__:

display(add)
    这是一个函数

但是，说明性文档的功能还远不止此，它还可以用来包含一些测试代码，以测试该成员（函数、类、类方法）的功能是否正确。值得一提的是，说明性文档中测试该成员的代码和实际调用该成员时使用的代码是一样的，只不过作为测试代码，它有特定的编写格式。

在函数、类或类方法的说明性文档中，以>>>作为开始的内容就表示一行测试代码，并且接下来的一行则明确该测试代码的输出结果，以上面程序为例，为 display() 函数添加测试代码如下：

'''
这是一个函数

>>> display("http://c.biancheng.net/python/")
http://c.biancheng.net/python/
>>> display("http://c.biancheng.net/java/")
http://c.biancheng.net/java/
'''

可以看到，我们为 display() 函数添加了 2 个测试代码，并且指定了该函数应该输出的正确结果。在此基础上，如果想执行测试代码，还需借助 doctest 模块中的 testmod() 函数。例如，修改上面程序如下所示：

import doctest

def display(add):
    '''
    这是一个函数
    >>> display("http://c.biancheng.net/python/")
    http://c.biancheng.net/python/
    >>> display("http://c.biancheng.net/java/")
    http://c.biancheng.net/java/
    '''
    print(add)
   
class my_cla:
    '''
    这是一个类
    >>> myClass = my_cla()
    >>> myClass.say("http://c.biancheng.net/shell/")
    http://c.biancheng.net/shell/
    >>> myClass.say("http://c.biancheng.net")
    abc
    '''
    def say(self,add):
        '''
        这是一个类实例方法
        '''
        print(add)
doctest.testmod()

可以看到，我们为 display() 函数以及 my_cla 类都添加了测试代码，同时还调用 doctest 模块中的 testmod() 函数。执行该程序，输出结果为：

**********************************************************************
File "C:/Users/mengma/Desktop/demo.py", line 20, in __main__.my_cla
Failed example:
    myClass.say("http://c.biancheng.net")
Expected:
    abc
Got:
    http://c.biancheng.net
**********************************************************************
1 items had failures:
   1 of   3 in __main__.my_cla
***Test Failed*** 1 failures.

该输出结果中，仅显示了执行错误的测试代码，所谓执行错误，指的是规定的测试代码的输出结果和运行该测试代码时的输出结果不一致。显然，对于上面所有的测试代码中，当调用 my_cls.say("http://c.bianchegn.net") 时，正常就应该输出 “http://c.biancheng.net”这个字符串，而不应该输出“abc”，这里仅是为了让读者看到使用 doctest.testmod() 函数的效果。

因此，在执行 doctest.testmod() 函数时，它会执行该模块中各成员说明性文档包含的测试代码，并将执行结果和指定的结果做比对，如果一致，则什么也不输出；反之，则输出以下提示信息：

1. 显示在哪个源文件的哪一行。
2. Failed example，显示是哪个测试用例出错了。
3. Expected，显示程序期望的输出结果。也就是在“>>>命令”的下一行给出的运行结果，它就是期望结果。
4. Got，显示程序实际运行产生的输出结果。只有当实际运行产生的输出结果与期望结果一致时，才表明该测试用例通过。