本文介绍如何使用 pytest 的 monkeypatch 机制，在同一 Python 环境中安全、可靠地模拟 tomllib 模块不可用的情形，从而完整覆盖 __version__ 加载逻辑的两个分支（直接解析 TOML vs 回退至 importlib.metadata）。
本文介绍如何使用 pytest 的 `monkeypatch` 机制，在同一 python 环境中安全、可靠地模拟 `tomllib` 模块不可用的情形，从而完整覆盖 `__version__` 加载逻辑的两个分支（直接解析 toml vs 回退至 `importlib.metadata`）。
在现代 Python 项目中，通过 pyproject.toml 提取版本号是一种常见实践。但 tomllib 自 Python 3.11 才正式进入标准库，为保证向后兼容，通常需使用 try/except ImportError 进行降级处理——这要求测试必须同时验证「有 tomllib」和「无 tomllib」两种路径。然而，手动切换 Python 版本或维护多个虚拟环境不仅低效，还违背“可复现、易执行”的测试原则。
幸运的是，pytest 提供了强大的 monkeypatch fixture，它允许我们在测试运行时动态修改模块状态，而无需改动真实环境。其中最精准的方式是篡改 sys.modules 缓存：Python 导入系统会首先检查 sys.modules，若键存在（即使值为 None），就不会尝试实际导入。因此，将 'tomllib' 显式设为 None，即可稳定触发 ImportError 分支。
以下是一个可直接集成到项目中的完整测试示例：
# test_version.py
import sys
from pathlib import Path
def get_version():
from typing import Any
from importlib import metadata
try:
import tomllib
# 注意：实际项目中应使用 __file__ 定位 pyproject.toml，而非硬编码路径
pyproject_path = Path(__file__).parent.parent / "pyproject.toml"
if not pyproject_path.exists():
raise FileNotFoundError("pyproject.toml not found")
with open(pyproject_path, "rb") as f:
pyproject: dict[str, Any] = tomllib.load(f)
return pyproject["tool"]["poetry"]["version"]
except (ImportError, KeyError, FileNotFoundError):
return metadata.version(__package__ or __name__)
def test_version_with_tomllib():
"""验证 tomllib 可用时，正确从 pyproject.toml 解析版本"""
version = get_version()
assert isinstance(version, str)
assert len(version) > 0
def test_version_without_tomllib(monkeypatch):
"""验证 tomllib 不可用时，回退至 importlib.metadata.version"""
# 关键操作：让导入系统认为 tomllib 已被“假性导入”且失败
monkeypatch.setitem(sys.modules, "tomllib", None)
version = get_version()
assert isinstance(version, str)
assert len(version) > 0✅ 注意事项与最佳实践：
- 不要使用 del sys.modules['tomllib']：若模块从未被导入过，删除操作无效；而设为 None 能确保后续 import tomllib 必然抛出 ImportError。
- 避免污染全局状态：monkeypatch 默认作用于单个测试函数，作用域隔离良好；若需跨测试复用，可定义 autouse=True 的 fixture，但需谨慎。
- 路径健壮性：生产代码中切勿硬编码 "pyproject.toml"，应基于 __file__ 或包路径动态定位，否则测试可能因工作目录不同而失败。
- 异常捕获范围：原始逻辑中 except Exception 过于宽泛，建议显式捕获 (ImportError, KeyError, OSError)，既提高可读性，也避免掩盖真正的编程错误。
通过该方法，你无需额外环境即可实现 100% 分支覆盖率——无论运行在 Python 3.11+ 还是 3.9/3.10，都能在单次 pytest 执行中完成双路径验证，显著提升 CI 稳定性与本地开发效率。
