怎么用python-mdoctest测文档里的示例?
详细讲解如何使用 python -m doctest 自动化测试 Markdown、reStructuredText 及纯文本文档中的 Python 示例代码,包含 REPL 语法规范、调试比对技巧、高级指令及 CI 自动化落地。
在维护开源库或接口文档时,最常见的技术脱节莫过于文档里的代码无法运行——函数改了参数、重构调整了返回值,而文档里的示例依然停留在几个月前的老版本,直接导致初学者复制代码后遭遇报错。解决这个问题的直接手段,就是使用 Python 原生内置的 doctest 模块,即通过命令行 python -m doctest 目标文档路径,直接提取 Markdown、reStructuredText 或纯文本中的交互式代码段并自动执行测试。本文将拆解如何书写规范的交互式文档代码、如何运行与排查差异,以及如何将文档测试接入持续集成流程。
一、python -m doctest 的核心机制
开发者常说的 python-mdoctest,实际上是指通过 Python 解释器的 -m 开关运行内置的 doctest 模块。Python 官方文档通常将 doctest 用在代码文件的 docstring 内部,但它同样原生支持对独立文本文件(如 README.md、tutorial.rst 或纯文本文件)进行全量扫描。
当执行 python -m doctest 文件名 时,测试引擎并不会关心外层的文档排版、图片或非代码文字,而是逐行扫描文本流,专门定位带有 Python 交互式提示符(即 >>> 和连续输入提示符 ...)的代码行。引擎会在一个独立的命名空间中执行这些指令,抓取标准输出与求值结果,再与紧随其后的文本行进行精确比对。如果输出完全相符,则判定用例通过;若存在字符差异或抛出未声明的异常,则打印差异报告(Diff)并抛出非零退出码。
二、文档内代码示例的正确书写规范
许多开发者尝试在 Markdown 中运行 python -m doctest 时失败,根本原因并非工具本身,而是代码块的书写方式不符合 doctest 的语法要求。doctest 原生模拟的是 Python 终端交互式命令行(REPL)的输入输出形态,而不是常规的纯脚本文件。
1. 关键书写规则
- 必须带有 REPL 提示符: 每段待测代码的首行必须以
>>>(三个大于号加一个空格)开头。如果不写>>>,doctest 会将其视为普通的叙述性文字而直接跳过。 - 多行代码与缩进使用
...: 如果代码包含函数定义、if分支或跨行列表,后续行必须以...(三个英文点加一个空格)开头,保持与 Python 交互式命令行一致的缩进格式。 - 预期输出紧随其后: 表达式求值结果或
print()输出必须紧跟在命令行的下一行,不要加>>>。 - 空行截断规则: doctest 默认将代码下方的首个空白行视为“输出结束标记”。如果示例的预期输出本身包含空行,需要使用特殊占位符
<BLANKLINE>标记。
三、具体操作步骤:从本地执行到验证诊断
掌握了格式规范后,我们可以通过一个完整的演练过程,在本地运行文档测试并理解其反馈机制。
第 1 步:创建待测文档
在项目根目录下创建一个 README.md,写入以下包含基础运算、导入和异常场景的交互式示例:
# 数学工具箱示例
这是一个演示文档。以下代码块展示了模块的核心用法:
```python
>>> from math import ceil, floor
>>> ceil(4.2)
5
>>> floor(4.8)
4
>>> 1 / 0
Traceback (most recent call last):
...
ZeroDivisionError: division by zero
```
第 2 步:运行基础测试命令
在终端中切换到该文件所在目录,执行以下命令:
python -m doctest README.md
如果没有任何屏幕输出,且终端返回码为 0,这代表文档内的所有用例全部测试通过。为了确认其退出状态码,可以在 Linux/macOS 终端紧接着输入 echo $?(Windows CMD 对应 echo %ERRORLEVEL%),返回值应为 0。
第 3 步:开启详细模式(-v)查看测试明细
在开发或调试阶段,直接返回空白往往让人缺乏直观感受。添加 -v(verbose)参数可以列出每个用例的尝试细节、期望值以及判定结果:
python -m doctest -v README.md
from math import ceil, floor
Expecting nothing
ok
Trying:
ceil(4.2)
Expecting:
5
ok
Trying:
floor(4.8)
Expecting:
4
ok
Trying:
1 / 0
Expecting:
Traceback (most recent call last):
...
ZeroDivisionError: division by zero
ok
1 items passed all tests:
4 tests in README.md
4 tests in 1 items.
4 passed and 0 failed.
Test passed.
四、处理常见比对失败与高频指令(Directives)
在实际测试中,直接字面比对往往会遭遇动态数据的干扰。例如对象的内存地址(<object at 0x7fa...>)、浮点数末尾微小扰动、多重空格或者异常堆栈里的环境绝对路径。直接比对必然导致测试崩溃。Python 为此提供了内联指令系统(Directives),以注释形式写在待测行末尾,灵活控制比对策略。
1. 省略动态不确定内容:+ELLIPSIS
当输出内容包含会随环境变化的动态字符(如内存地址、时间戳或超长列表中间部分)时,在代码行末尾加上 # doctest: +ELLIPSIS,即可用 ... 代表任意长度的字符:
```python
>>> class User:
... pass
>>> User() # doctest: +ELLIPSIS
<__main__.User object at 0x...>
```
2. 忽略空白符差异:+NORMALIZE_WHITESPACE
Markdown 渲染或排版时,连续空格、制表符或换行符容易被意外合并或修改。+NORMALIZE_WHITESPACE 会将多余的连续空白字符视作单个空格,并允许跨行对其:
```python
>>> [1, 2, 3, 4, 5] # doctest: +NORMALIZE_WHITESPACE
[1, 2,
3, 4, 5]
```
3. 跳过特定示例:+SKIP
如果某些文档示例依赖特定操作系统环境、需要网络连接或执行时间过长,可以使用 +SKIP 跳过当前行:
```python
>>> import os
>>> os.remove('/etc/hosts') # doctest: +SKIP
```
# doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE。
五、工程化落地:接入 CI/CD 与 Pytest
仅靠开发者在本地手动运行 python -m doctest 难以彻底杜绝文档腐化。最有效的实践是将其固化为团队提交代码时的强制卡点。
1. 与 Pytest 深度整合
现代化 Python 项目通常使用 pytest 作为统一测试运行器。通过安装并指定参数,pytest 可以直接在执行常规单元测试的同时,自动搜寻 Markdown 文档并运行其中的 doctest:
pytest --doctest-glob="*.md"
如果希望项目每次运行 pytest 时默认测试文档,可以在根目录的 pyproject.toml 或 setup.cfg 中固化配置:
# pyproject.toml 配置示例
[tool.pytest.ini_options]
addopts = "--doctest-modules --doctest-glob='*.md'"
2. GitHub Actions 自动化门禁
在持续集成流水线中加入文档测试步骤非常轻量,不需要安装重型依赖:
# .github/workflows/docs-test.yml
name: 文档示例自动化测试
on: [push, pull_request]
jobs:
test-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 设置 Python 环境
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: 安装项目依赖
run: |
pip install .
- name: 运行 README 文档测试
run: |
python -m doctest README.md
六、总结与实践建议
通过 python -m doctest 文档路径 测试 Markdown 或文本中的代码,核心价值不仅在于验证代码本身是否能跑通,更在于促使维护者以严肃的态度对待文档中的每一处承诺。文档不再只是静止的说明文本,而是整个项目测试用例集的一部分。
在实际落地时,建议保持两点原则:一是示例尽量小而精,将复杂流程拆解为简明输入输出,避免在文档中编写耗时过长或依赖复杂外部环境的代码;二是善用内联指令化解偶发抖动,使用 +ELLIPSIS 和 +NORMALIZE_WHITESPACE 保持比对的鲁棒性。配合 CI 自动构建流水线,即可在最低维护成本下,永久终结“文档代码一跑就错”的尴尬局面。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













