一、核心概念解析1.1 基础定义什么是“文档即测试”想象一下你在教朋友玩一个新桌游普通文档你写了一本规则书里面说“玩家每次可以抽2张牌”文档即测试你不仅写了规则还附加了一句“比如小张有3张牌抽2张后他现在有5张牌”而且这句话本身就是可执行的测试doctest模块做的就是这件事它扫描你的文档字符串docstring找出看起来像Python交互式会话的示例然后运行这些示例验证结果是否与文档中写的一致。核心思想文档中的示例应该是真实可运行的代码如果示例不能运行或结果不对说明文档过时了文档和代码永远同步因为不同步就会测试失败1.2 基本语法最简单的doctest# doctest_basic.pydefadd_numbers(a,b): 将两个数字相加。 示例: add_numbers(2, 3) 5 add_numbers(-1, 1) 0 支持浮点数: add_numbers(1.5, 2.5) 4.0 returnabdefgreet(name,formalFalse): 根据形式返回问候语。 基本用法: greet(Alice) Hello, Alice! 正式问候: greet(Bob, formalTrue) Good day, Mr. Bob. 注意空白字符也会被比较: greet(Charlie) # 这行只是注释不会被执行 Hello, Charlie! ifformal:returnfGood day, Mr.{name}.returnfHello,{name}!if__name____main__:# 运行这个文件中的所有doctestimportdoctest doctest.testmod(verboseTrue)# verboseTrue会显示详细信息运行这个脚本python doctest_basic.py你会看到类似这样的输出Trying: add_numbers(2, 3) Expecting: 5 ok Trying: add_numbers(-1, 1) Expecting: 0 ok ...doctest的语法规则开头的是要执行的代码下一行是期望的输出如果输出匹配测试通过空行用于分隔不同的测试用例以#开头的是注释不会被执行1.3 核心特点为什么使用doctest文档与代码同步示例过时测试会失败提醒你更新降低学习成本新开发者看文档就能知道函数怎么用轻量级测试简单的功能用doctest比写完整的单元测试更快捷代码即文档文档字符串本身就是可执行的示例库教育价值教别人用你的代码时文档中的示例都是验证过的二、应用场景详解2.1 为函数和类编写可测试文档# doctest_functions_classes.py 数学工具函数集合。 这个模块提供了一些常用的数学计算函数。 defcalculate_discount(price,discount_rate): 计算打折后的价格。 参数: price: 原价 discount_rate: 折扣率0.0到1.0之间 返回: 折后价格 示例: calculate_discount(100, 0.2) # 8折 80.0 calculate_discount(50, 0) # 不打折 50.0 calculate_discount(200, 0.5) # 5折 100.0 边界情况: calculate_discount(0, 0.3) # 0元商品 0.0 ifnot0discount_rate1:raiseValueError(折扣率必须在0到1之间)returnprice*(1-discount_rate)classBankAccount: 简单的银行账户类。 示例: account BankAccount(Alice, 1000) account.balance 1000 account.deposit(500) 存入500元当前余额1500元 account.withdraw(300) 取出300元当前余额1200元 account.withdraw(2000) # 余额不足 Traceback (most recent call last): ... ValueError: 余额不足 def__init__(self,owner,initial_balance0):self.ownerowner self.balanceinitial_balancedefdeposit(self,amount):存款ifamount0:raiseValueError(存款金额必须大于0)self.balanceamountreturnf存入{amount}元当前余额{self.balance}元defwithdraw(self,amount):取款ifamount0:raiseValueError(取款金额必须大于0)ifamountself.balance:raiseValueError(余额不足)self.balance-amountreturnf取出{amount}元当前余额{self.balance}元def__str__(self):returnf{self.owner}的账户余额{self.balance}元defrun_doctests():运行这个模块的doctestimportdoctest# 安静模式只显示失败信息print(运行doctest测试...)resultdoctest.testmod(verboseFalse)ifresult.failed0:print(f✓ 所有{result.attempted}个测试通过)else:print(f✗{result.failed}个测试失败)if__name____main__:run_doctests()2.2 在模块级别编写文档测试不仅函数和类可以有doctest整个模块也可以在文档字符串中包含测试# math_utils.py 数学工具模块。 这个模块提供一些常用的数学计算功能。 模块级别的示例: from math_utils import is_prime, fibonacci is_prime(17) True is_prime(9) False fibonacci(6) # 斐波那契数列: 0,1,1,2,3,5,8,13... 8 fibonacci(10) 55 defis_prime(n):判断一个数是否为质数。ifn2:returnFalseforiinrange(2,int(n**0.5)1):ifn%i0:returnFalsereturnTruedeffibonacci(n):计算第n个斐波那契数。ifn0:raiseValueError(n必须是非负整数)a,b0,1for_inrange(n):a,bb,abreturna# 模块级别的测试用例不在任何函数内 测试边缘情况: is_prime(1) False is_prime(2) # 2是质数 True fibonacci(0) 0 fibonacci(1) 1 if__name____main__:importdoctest doctest.testmod()2.3 最佳实践编写有效的doctest原则1示例应该简单明了# good_examples.pydefprocess_items(items): 处理项目列表。 好的示例简单直接: process_items([1, 2, 3]) [2, 4, 6] 不好的示例太复杂: process_items([x for x in range(10) if x % 2 0]) [0, 4, 8, 12, 16] # 这个示例本身就需要理解失去了文档的意义 return[x*2forxinitems]deffind_max(numbers): 找到列表中的最大值。 好的示例展示常见情况: find_max([3, 1, 4, 1, 5, 9]) 9 好的示例展示边缘情况: find_max([-5, -10, -1]) -1 好的示例展示错误处理: find_max([]) Traceback (most recent call last): ... ValueError: 列表不能为空 ifnotnumbers:raiseValueError(列表不能为空)returnmax(numbers)原则2使用ELLIPSIS选项处理可变输出# doctest_ellipsis.pyimportrandomimportdatetimedefget_current_info(): 获取当前信息。 由于时间和随机性输出会变化我们可以用...匹配部分输出: info get_current_info() info[timestamp].year datetime.datetime.now().year True 0 info[random_number] 100 True info[status] ok return{timestamp:datetime.datetime.now(),random_number:random.randint(0,100),status:ok}defgenerate_id(): 生成随机ID。 使用ELLIPSIS忽略变化的部分: generate_id() # doctest: ELLIPSIS ID-... 更精确的匹配: id_str generate_id() id_str.startswith(ID-) and len(id_str) 10 True importuuidreturnfID-{uuid.uuid4().hex[:6]}if__name____main__:importdoctest# 启用ELLIPSIS选项doctest.testmod(optionflagsdoctest.ELLIPSIS)原则3组织大型测试用例# doctest_organization.py 数据处理工具。 这个模块包含多个相关的数据处理函数。 defnormalize_data(data): 标准化数据使所有值在0-1范围内。 示例: normalize_data([1, 2, 3, 4, 5]) [0.0, 0.25, 0.5, 0.75, 1.0] normalize_data([10, 20]) [0.0, 1.0] ifnotdata:return[]min_valmin(data)max_valmax(data)ifmin_valmax_val:return[0.5]*len(data)return[(x-min_val)/(max_val-min_val)forxindata]deffilter_outliers(data,threshold2): 过滤掉离群值。 基本用法: filter_outliers([1, 2, 3, 4, 100]) [1, 2, 3, 4] 自定义阈值: filter_outliers([1, 2, 3, 4, 10], threshold1.5) [1, 2, 3, 4] importstatisticsiflen(data)2:returndata mean_valstatistics.mean(data)stdev_valstatistics.stdev(data)return[xforxindataifmean_val-threshold*stdev_valxmean_valthreshold*stdev_val]# 为整个模块编写集成测试 集成测试示例: data [1, 2, 3, 100, 4, 5] filtered filter_outliers(data) filtered [1, 2, 3, 4, 5] normalized normalize_data(filtered) normalized # doctest: ELLIPSIS [0.0, 0.25, 0.5, 0.75, 1.0] if__name____main__:importdoctest# 运行测试显示详细信息doctest.testmod(verboseTrue)三、高级技巧3.1 控制测试执行选项doctest提供了多种选项来控制测试行为# doctest_options.py 测试选项演示。 这个模块展示如何使用不同的doctest选项。 defexample_with_output(): 有输出的函数示例。 默认情况下doctest会精确比较输出: print(Hello\\nWorld) Hello World 使用NORMALIZE_WHITESPACE可以忽略空白差异: [a, b, c] # doctest: NORMALIZE_WHITESPACE [a, b, c] 注意上面列表的表示实际输出是[a, b, c]但空格可能不同 passdefexample_with_exceptions(): 异常处理示例。 测试异常时我们通常只关心异常类型: 1 / 0 Traceback (most recent call last): ZeroDivisionError: division by zero 使用ELLIPSIS可以只匹配部分异常信息: int(not a number) # doctest: ELLIPSIS Traceback (most recent call last): ... ValueError: ... passdefexample_with_float(): 浮点数比较示例。 浮点数比较有精度问题: 0.1 0.2 # 这实际上等于0.30000000000000004 0.30000000000000004 我们可以允许一定的误差: abs((0.1 0.2) - 0.3) 0.000001 True 或者使用approx函数: from math import isclose isclose(0.1 0.2, 0.3) True pass# 模块级别的选项设置 全局设置选项: import doctest doctest.set_unittest_reportflags(doctest.REPORT_NDIFF) if__name____main__:importdoctest# 设置多个选项options(doctest.ELLIPSIS|# 允许使用...匹配任意输出doctest.NORMALIZE_WHITESPACE|# 忽略空白差异doctest.IGNORE_EXCEPTION_DETAIL# 忽略异常详情只检查类型)# 运行测试resultdoctest.testmod(optionflagsoptions,verboseTrue)print(f\n测试结果:{result.attempted}个测试尝试{result.failed}个失败)3.2 在测试文件中使用doctest除了在代码文件中嵌入doctest你还可以创建独立的测试文件# test_example.txt 这是独立的doctest文件。 我们可以在这里写测试而不影响源代码文件。 from math_utils import is_prime is_prime(2) True is_prime(4) False is_prime(17) True from math_utils import fibonacci fibonacci(0) 0 fibonacci(1) 1 fibonacci(5) 5 fibonacci(10) 55 然后创建一个Python脚本来运行这个测试文件# run_doctest_file.py 运行独立的doctest文件。 importdoctestimportsysdeftest_text_file():测试文本文件中的doctestprint(测试独立的doctest文件...)# 运行文本文件中的测试resultdoctest.testfile(test_example.txt,optionflagsdoctest.ELLIPSIS,verboseTrue)returnresultdeftest_external_module():测试外部模块的doctestprint(\n测试外部模块的doctest...)# 假设我们有一个math_utils.py模块try:importmath_utils resultdoctest.testmod(math_utils,verboseFalse)print(fmath_utils测试:{result.attempted}尝试{result.failed}失败)exceptImportError:print(找不到math_utils模块跳过测试)if__name____main__:# 测试文本文件result1test_text_file()# 测试外部模块test_external_module()# 总结ifresult1.failed0:print(\n✓ 所有测试通过)else:print(f\n✗ 有{result1.failed}个测试失败)sys.exit(1)3.3 与unittest框架集成doctest可以与Python的标准单元测试框架unittest无缝集成# doctest_unittest_integration.py doctest与unittest集成示例。 这个模块展示如何将doctest作为unittest的一部分运行。 defmultiply(a,b): 两个数相乘。 示例: multiply(2, 3) 6 multiply(0, 100) 0 multiply(-5, 4) -20 returna*bdefdivide(a,b): 两个数相除。 示例: divide(10, 2) 5.0 divide(5, 2) 2.5 除零错误: divide(10, 0) Traceback (most recent call last): ZeroDivisionError: division by zero returna/b# unittest测试类importunittestimportdoctestclassTestMathFunctions(unittest.TestCase):测试数学函数的单元测试deftest_multiply_basic(self):测试基本的乘法self.assertEqual(multiply(2,3),6)self.assertEqual(multiply(0,5),0)self.assertEqual(multiply(-3,4),-12)deftest_divide_basic(self):测试基本的除法self.assertEqual(divide(10,2),5.0)self.assertEqual(divide(9,3),3.0)deftest_divide_by_zero(self):测试除零错误withself.assertRaises(ZeroDivisionError):divide(10,0)defload_tests(loader,tests,ignore): 为unittest加载doctest。 这个函数会被unittest自动调用将doctest添加到测试套件中。 # 添加当前模块的doctesttests.addTests(doctest.DocTestSuite())# 也可以添加其他模块的doctest# tests.addTests(doctest.DocTestSuite(other_module))returntestsif__name____main__:# 运行unittest会自动包含doctestunittest.main(verbosity2)四、实战案例为一个小型工具库编写文档测试让我们为一个简单的字符串处理库编写完整的文档测试# string_tools.py 字符串处理工具库。 一个简单但实用的字符串处理函数集合。 defreverse_string(s): 反转字符串。 示例: reverse_string(hello) olleh reverse_string(Python) nohtyP reverse_string() # 空字符串 reverse_string(a) # 单个字符 a returns[::-1]defis_palindrome(s,ignore_spacesFalse,ignore_caseFalse): 检查字符串是否是回文。 参数: s: 要检查的字符串 ignore_spaces: 是否忽略空格 ignore_case: 是否忽略大小写 返回: 如果是回文返回True否则返回False 示例: is_palindrome(racecar) True is_palindrome(hello) False is_palindrome(A man a plan a canal Panama) False is_palindrome(A man a plan a canal Panama, ignore_spacesTrue, ignore_caseTrue) True is_palindrome(Was it a car or a cat I saw, ignore_spacesTrue, ignore_caseTrue) True ifignore_spaces:s.join(s.split())ifignore_case:ss.lower()returnss[::-1]defcount_vowels(s,include_yFalse): 统计字符串中的元音字母数量。 参数: s: 字符串 include_y: 是否将y视为元音 返回: 元音字母的数量 示例: count_vowels(hello) 2 count_vowels(python) 1 count_vowels(rhythm) 0 count_vowels(rhythm, include_yTrue) 1 count_vowels(Hello World!) 3 vowelsaeiouAEIOUifinclude_y:vowelsyYreturnsum(1forcharinsifcharinvowels)defslugify(text,separator-): 将文本转换为URL友好的slug格式。 参数: text: 原始文本 separator: 单词分隔符 返回: slug格式的字符串 示例: slugify(Hello World!) hello-world slugify(Python 3.9 Release Notes) python-3-9-release-notes slugify(Data Science 101: Introduction, separator_) data_science_101_introduction slugify( Multiple Spaces Here ) multiple-spaces-here slugify(SpecialChars#Removed!) specialcharsremoved importre# 转换为小写texttext.lower()# 移除非字母数字字符用空格替换textre.sub(r[^a-z0-9], ,text)# 移除首尾空格texttext.strip()# 用分隔符替换空格textre.sub(r\s,separator,text)returntext# 模块级别的综合测试 综合测试示例: 测试字符串反转: reverse_string(Python is awesome) emosewa si nohtyP 测试回文检测: test_cases [ ... (racecar, True), ... (hello, False), ... (A man a plan a canal Panama, False), ... ] all(is_palindrome(s) expected for s, expected in test_cases) True 测试元音计数: count_vowels(The quick brown fox jumps over the lazy dog) 11 测试slug生成: slugify(Testing 1, 2, 3!) testing-1-2-3 if__name____main__:importdoctestprint(*50)print(运行字符串工具库的doctest)print(*50)# 运行测试resultdoctest.testmod(verboseTrue)print(*50)ifresult.failed0:print(f✅ 所有{result.attempted}个测试通过)else:print(f❌{result.failed}个测试失败)运行这个脚本你会看到详细的测试输出包括每个测试用例的执行情况。五、注意事项5.1 使用限制不适合复杂测试doctest适合简单的示例验证不适合复杂的测试逻辑输出必须精确默认情况下输出必须完全匹配包括空格和换行有副作用示例代码会实际执行可能有副作用性能考虑文档中的示例每次运行测试都会执行可读性过多的测试示例可能影响文档的可读性5.2 常见问题Q: doctest和unittest哪个更好A: 不是更好而是用途不同doctest用于验证文档中的示例确保文档正确unittest用于编写全面的测试套件包括各种边界情况Q: 如何处理随机输出或变化输出A: 使用ELLIPSIS选项或者用条件判断而不是精确匹配importrandomrandom.randint(1,100)# doctest: ELLIPSIS...Q: doctest能测试私有函数吗A: 可以但不建议。文档测试应该关注公共API。Q: 测试失败时如何调试A: 使用doctest.testmod(verboseTrue)查看详细输出或者用pdb调试失败的测试。Q: 如何在CI/CD中运行doctestA: 在测试命令中添加python -m doctest your_module.py或者通过unittest运行。5.3 替代方案unittest/pytest需要全面的测试覆盖时文档生成工具Sphinx的autodoc扩展可以自动生成API文档示例代码库维护独立的使用示例库交互式教程Jupyter Notebook作为交互式文档类型提示配合mypy进行静态类型检查何时选择替代方案需要测试覆盖率报告 → 使用pytest大型项目需要完整测试套件 → 使用unittest需要生成HTML文档 → 使用Sphinx需要交互式教学 → 使用Jupyter Notebook需要静态类型检查 → 使用mypy 类型提示六、总结通过本文的学习你应该已经掌握了✅doctest基础如何在文档字符串中编写可执行示例✅语法规则和期望输出的格式✅测试选项ELLIPSIS、NORMALIZE_WHITESPACE等高级选项✅集成测试如何与unittest框架集成✅最佳实践编写清晰、有用的文档测试doctest的核心价值文档可靠性确保文档中的示例永远正确开发效率写文档的同时就完成了测试学习友好新开发者通过文档就能理解代码用法代码质量鼓励开发者提供完整、可运行的示例维护便利API变化时过时的文档会自动测试失败使用建议从简单开始先为关键函数添加几个基本示例关注公共API优先为重要的、公开的函数编写文档测试保持简洁每个示例应该简单明了突出重点定期运行将doctest集成到你的开发流程中适度使用不是所有函数都需要文档测试找到平衡点你在项目中用过doctest吗有什么有趣的经验或教训或者你认为文档测试在实际项目中到底有多大价值欢迎在评论区分享你的看法和经验