python：文档测试

在Python中，文档测试（doctest）是一种通过嵌入示例代码和预期输出来测试文档字符串（docstrings）和文档中的代码片段的方法。它允许开发者在编写文档的同时，确保文档中的代码示例是准确和有效的。doctest模块会读取文档字符串或指定文件中的代码示例，执行它们，并比较实际输出与预期输出。

使用doctest的步骤

1. 编写文档字符串：
   在函数、类或模块的文档字符串中，包含你想要测试的示例代码和预期输出。使用>>>提示符来标记示例代码，并紧跟期望的输出结果。

   python复制代码

   	def add(a, b):
   	"""
   	Return the sum of a and b.
   	>>> add(1, 2)
   	3
   	>>> add(-1, 1)
   	0
   	>>> add(-1, -1)
   	-2
   	"""
   	return a + b

2. 运行doctest：
   使用doctest模块来运行你的文档测试。你可以通过命令行或脚本方式来执行。

   • 命令行：使用-m doctest选项来运行doctest模块，并指定包含文档字符串的Python文件。

     bash复制代码

     python -m doctest your_module.py

   • 脚本方式：在你的Python脚本中导入doctest模块，并调用doctest.testmod()函数来运行当前模块中的doctest。

     python复制代码

     	if __name__ == "__main__":
     	import doctest
     	doctest.testmod()

3. 查看结果：
   doctest会输出测试结果，包括哪些测试通过了，哪些失败了，以及失败的详细信息（如实际输出与预期输出的差异）。

注意

• 确保文档字符串中的示例是有效的Python代码：doctest会尝试执行这些代码，因此它们必须是语法正确的Python语句。
• 使用省略号（...）表示多行输出：如果预期输出是多行的，并且你不想逐行比较，可以使用省略号来表示。
• 使用doctest.ELLIPSIS标志：如果输出中包含无法精确匹配的动态内容（如时间戳），可以使用doctest的ELLIPSIS标志来允许部分匹配。
• 使用doctest.NORMALIZE_WHITESPACE标志：忽略输出中的空白字符差异（如空格和换行符的数量）。

示例

以下是一个完整的示例，展示了如何编写和运行doctest：

python复制代码

	def factorial(n):
	"""
	Calculate the factorial of a number.
	>>> factorial(5)
	120
	>>> factorial(10)
	3628800
	>>> factorial(0)
	1
	"""
	if n == 0:
	return 1
	else:
	return n * factorial(n - 1)
	if __name__ == "__main__":
	import doctest
	doctest.testmod()

将上述代码保存为factorial.py，然后在命令行中运行：

bash复制代码

python factorial.py

如果文档字符串中的示例代码都正确执行并产生了预期的输出，doctest将报告所有测试通过。如果有任何不匹配，doctest将指出哪些测试失败了，并提供实际输出与预期输出的差异。