如何在Python多目录项目结构下正常运行带跨模块依赖的单元测试

问题根因 #

这个矛盾是Python模块搜索路径的运行规则决定的：

• Python导入模块时，会优先检索启动解释器时的当前工作目录，再按顺序检索环境变量配置的路径。
• 直接运行src/B.py时，解释器的当前工作目录就是src目录，能直接匹配到同目录下的A.py，from A import foo的写法可以正常执行。
• 跑测试时一般在项目根目录启动测试工具，此时解释器的工作目录是项目根，根本检索不到src路径下的A模块，自然抛出No module named A的报错。
• 如果把导入改成from .A import foo的相对导入形式，这类导入要求当前文件必须作为包的内部模块被加载，不能直接作为顶层脚本运行，就会导致直接执行B.py时抛出相对导入无父包的错误。

可行解决方案 #

方案1：不改动原有导入逻辑，自动补全搜索路径 #

不需要修改B.py里的导入语句，在项目根目录新建conftest.py（pytest会自动加载该文件的配置），写入以下内容：

import sys
from pathlib import Path

# 自动将src目录加入Python模块搜索路径
sys.path.insert(0, str(Path(__file__).parent / "src"))

配置完成后两种场景都能正常运行：

• 直接执行B.py时，原有导入逻辑不受影响
• 运行测试时，pytest启动会先执行这个配置文件，自动把src加入搜索路径，不会再出现导入报错

如果不用pytest，也可以在执行测试前临时设置环境变量PYTHONPATH=./src，效果完全一致。

方案2：规范包结构，统一绝对导入逻辑 #

1. 调整目录结构，给相关目录加__init__.py标记，让Python识别为正式包：

project
    ├── __init__.py
    ├── src
    │   ├── __init__.py
    │   ├── A.py
    │   └── B.py
    tests
    ├── test_b.py

2. 将B.py里的导入语句改为从项目根出发的绝对导入：

from src.A import foo

3. 调整运行命令，避免直接执行脚本的路径检索问题：

• 跑测试时在最外层项目根目录执行pytest tests/，此时Python能正常识别src为顶级包，导入不会出错
• 直接运行B.py时，不用python src/B.py的方式，改用模块启动命令python -m src.B，这种启动方式会自动把项目根目录加入搜索路径，程序可以正常执行。

方案3：在B.py内动态补全路径（零外部配置） #

如果不想新增项目配置文件、也不想调整运行命令，可以在B.py的最顶部，导入A模块之前动态加入当前文件所在目录到搜索路径：

# B.py 顶部新增的路径处理代码
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent))

# 原有导入逻辑保持不变
from A import foo

这种方式无论直接运行B.py，还是被测试模块导入，都能准确检索到同目录下的A.py文件，不需要额外配置。

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