为什么pytest启用doctest-modules后无doctest的函数覆盖率也上升

现象原因 #

启用--doctest-modules参数后，pytest的doctest插件为了扫描所有模块中是否存在docstring形式的doctest用例，会在覆盖率统计逻辑启动前，主动导入所有匹配规则的模块。
模块导入过程中，所有顶层代码都会被执行，包括函数定义语句、类定义语句、模块级变量赋值等，这部分执行的代码会被覆盖率工具统计为已覆盖。你给出的示例中test.py共2行代码：

• 第一行def test(x):是函数定义语句，导入时就会执行，所以被统计为已覆盖
• 第二行return x是函数内部逻辑，只有调用函数才会执行，导入时不会触发
  所以最终得到50%的覆盖率，和你测试的结果完全吻合。如果有其他模块在顶层代码中直接调用了test函数，那该模块被doctest插件导入时，还会触发test函数内部逻辑的执行，进而得到100%的覆盖率。

关闭该特性的方案 #

你可以根据自己的需求选择以下任意一种方案：

方案1：配置coverage跳过导入阶段的统计 #

在项目根目录新建.coveragerc配置文件，添加以下内容：

[run]
dynamic_context = test_function

该配置会让coverage仅统计测试用例（含doctest用例）执行过程中运行的代码，模块导入阶段的执行不会被纳入统计，符合你预期的「只有执行了doctest用例的代码才会提升覆盖率」的需求。

方案2：拆分doctest运行和覆盖率统计 #

如果你不需要统计doctest用例的覆盖率，可以将两个任务分开执行：

• 统计普通测试覆盖率时关闭doctest扫描：pytest --cov=test --no-doctest-modules
• 单独运行doctest校验时不统计覆盖率：pytest --doctest-modules --no-cov

方案3：指定doctest的扫描范围 #

如果你只有部分文件包含doctest用例，可以在setup.cfg中指定doctest仅扫描这些文件，避免无关模块被导入：

[pytest]
doctest_modules =
    路径/到/有doctest的模块1.py
    路径/到/有doctest的模块2.py

内容的提问来源于stack exchange，提问作者caldwellst