第十六章：开发工具-doctest:通过文档完成测试-起步

16.2 doctest:通过文档完成测试
doctest会运行文档中嵌入的例子，并验证它们是否能生成所期望的结果，来对源代码进行测试。它的做法是解析帮助文档的，找到例子，运行这些例子，然后将输出文本与所期望的值进行比较。很多开发人员发现doctest比unittest更易于使用，因为如果采用最简单的形式，那么使用doctest之前无须学习新的API。不过，随着例子变得越来越复杂，由于缺乏固件管理，编写doctest测试可能会比使用unittest更麻烦。

16.2.1 起步
建立doctest的第一步是使用交互式解释器创建例子，然后把这些例子复制粘贴到模块的docstring中。在这里，my_function()给出了两个例子。

def my_function(a,b):
    """
    >>> my_function(2,3)
    6
    >>> my_function('a',3)
    'aaa'
    """
    return a * b

运行这些测试时，通过指定-m选项将doctest作为主程序。运行测试时通常不会生成输出，所以下面的例子包含了-v选项来得到更详细的输出。

例子并不总能独立地作为一个函数的解释，所以doctest还允许有包围文本。它会查找以解释器提示符(>>>)开头的行，找出测试用例的开始位置，用例以一个空行结束，或者以下一个解释器提示符结束。介于中间的文本会被忽略，并且它们可以采用任何格式(只要看上去不像是一个测试用例即可)。

def my_function(a,b):
    """Returns a * b.

    Works with numbers:

    >>> my_function(2,3)
    6

    and strings:

    >>> my_function('a',3)
    'aaa'
    """
    return a * b

更新的docstring中如果有包围文本，那么这些包围文本对人类读者更有用。由于它会被doctest忽略，所以结果是一样的。