在 Python 单元测试中，使用 mocker.patch 模拟模块级变量时，若误用 return_value 参数会导致变量被包装为 MagicMock，从而无法真实调用 Path 等类型的方法；应改用 new 参数直接替换变量值，确保类型与行为完全一致。
在 python 单元测试中，使用 `mocker.patch` 模拟模块级变量时，若误用 `return_value` 参数会导致变量被包装为 `magicmock`，从而无法真实调用 `path` 等类型的方法；应改用 `new` 参数直接替换变量值，确保类型与行为完全一致。
当你尝试通过 mocker.patch(..., return_value=...) 去“模拟”一个模块变量（如 DEFAULT = Path("/etc/config.yaml")）时，本质是将该变量伪装成一个可调用对象（callable）——即 MagicMock 实例。此时 DEFAULT 不再是 Path 对象，而是一个 mock，其 .touch()、.exists() 等方法虽不报错（因 MagicMock 默认允许任意属性访问和调用），但不会执行实际文件系统操作，导致 DEFAULT.touch(exist_ok=True) 静默失败，文件并未创建。
✅ 正确做法：使用 new 参数进行值替换（value replacement），而非模拟调用：
@pytest.fixture(autouse=True)
def mock_default(mocker, tmp_path):
"""Mock Default Config File Path as a real Path object."""
default_path = tmp_path / "config.yaml"
mocker.patch("mypackage.mymodule.DEFAULT", new=default_path)new= 会直接将模块中的 DEFAULT 绑定为指定的 Path 实例，保留其全部类型特性与行为（如 default_path.touch() 真实写入临时目录、default_path.read_text() 可读取内容等），测试具备真实性和可验证性。
⚠️ 注意事项：
- ❌ 避免对变量使用 return_value、side_effect 或 wraps —— 这些专为函数/方法模拟设计；
- ✅ 若需动态生成值（如每次 fixture 返回不同路径），仍可用 new= + lambda 或闭包，但更推荐在 fixture 内预计算后传入；
- ? mocker.patch 默认作用域为模块级变量；确认目标路径 "mypackage.mymodule.DEFAULT" 准确无拼写错误（尤其注意是否在 __init__.py 中重新导出）；
- ? 验证是否生效：在测试中打印 type(mypackage.mymodule.DEFAULT) 应输出 <class 'pathlib.Path'>，而非 <class 'unittest.mock.MagicMock'>。
总结：return_value 用于 mock 函数调用结果，new 才用于 替换变量本身。理解这一根本区别，是写出可靠、可调试、符合预期行为的单元测试的关键。
