Python文档测试主要使用doctest模块，它从docstring提取交互式示例自动验证代码；支持内联测试、外部文件测试及特殊指令处理异常和省略输出。
Python 中做文档测试主要使用 doctest 模块，它能从函数的文档字符串（docstring）中提取交互式 Python 示例，并自动运行这些示例来验证代码是否按预期工作。这种方式让测试和文档保持同步，既写说明又做测试。
1. 编写带测试用例的文档字符串
在函数或模块的 docstring 中，按照 Python 交互式解释器的格式写测试样例：
def add(a, b):
"""
返回两个数的和。
示例：
youjiankuohaophpcnyoujiankuohaophpcnyoujiankuohaophpcn add(2, 3)
5
youjiankuohaophpcnyoujiankuohaophpcnyoujiankuohaophpcn add(-1, 1)
0
youjiankuohaophpcnyoujiankuohaophpcnyoujiankuohaophpcn add(0, 0)
0
"""
return a + b
注意：>>> 表示输入，其后紧跟的是期望输出。doctest 会执行这些输入并检查输出是否一致。
2. 运行 doctest
可以在代码末尾添加以下内容，运行时自动检测所有 docstring 中的测试：
立即学习“Python免费学习笔记（深入）”；
if __name__ == "__main__":
import doctest
doctest.testmod()
保存为文件如 math_tool.py，在终端运行：
maven使用方法 中文WORD版
下载
本文档主要讲述的是maven使用方法；Maven是基于项目对象模型的（pom），可以通过一小段描述信息来管理项目的构建，报告和文档的软件项目管理工具。Maven将你的注意力从昨夜基层转移到项目管理层。Maven项目已经能够知道 如何构建和捆绑代码，运行测试，生成文档并宿主项目网页。希望本文档会给有需要的朋友带来帮助；感兴趣的朋友可以过来看看
python math_tool.py
如果所有测试通过，不会有任何输出。加上 -v 参数可查看详细结果：
python math_tool.py -v
3. 在独立文档文件中写测试
你也可以把测试写在纯文本文件中，比如 example.txt：
The add function >>> from math_tool import add >>> add(3, 4) 7
然后用 doctest 运行这个文件：
import doctest
doctest.testfile("example.txt")
4. 处理特殊情况
有些输出可能包含空格、异常或省略部分内容，可以使用特殊指令控制匹配行为：
-
忽略多余空白：使用
# doctest: +ELLIPSIS - 测试异常：直接写出 traceback
>>> print(list(range(10))) # doctest: +ELLIPSIS [0, 1, ..., 9]
>>> add("hello", 5)
Traceback (most recent call last):
File "", line 1, in
File ".../math_tool.py", line 10, in add
return a + b
TypeError: can only concatenate str (not "int") to str
基本上就这些。doctest 简单直接，适合教学、小项目或确保文档示例始终有效。对于复杂测试，建议搭配 unittest 或 pytest 使用。但日常写工具函数时，用 doctest 写例子顺便完成测试，很高效。
