如何在Python项目单元测试中正确引用convert_utils.py模块？

目录结构说明 #

项目根目录backend-app结构：

backend-app
├── Dockerfile
├── __init__.py
├── app
├── credentials-dev.json
├── requirements.txt
├── tests
└── venv

tests子目录结构：

tests
├── __init__.py
├── integration
│   ...
└── unit
    ├── __init__.py
    └── util
        ├── __init__.py
        └── test_convert_utils.py

目标模块convert_utils.py所在路径：

app
├── __init__.py
├── main.py
├── resources
│   ├── config-dev.yaml
│   └── credentials-dev.json
└── src
    ├── impl
    │   ...
    ├── model
    │   ...
    ├── service
        ...
    └── util
        ├── __init__.py
        ├── convert_utils.py

问题 #

如何在test_convert_utils.py中正确引用app/src/util/convert_utils.py？

解决方法 #

方法1：动态添加项目根目录到Python路径 #

在test_convert_utils.py的开头添加以下代码，将项目根目录加入Python的搜索路径：

import sys
import os

# 从当前测试文件目录向上回溯到项目根目录
root_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '../../../../'))
sys.path.append(root_dir)

# 现在可以直接导入目标模块
from app.src.util.convert_utils import *

方法2：使用相对导入（需按包方式运行测试） #

如果将tests视为项目包的一部分，可以用相对导入语法：

# 从当前测试文件向上跳3级到tests目录，再定位到app下的目标模块
from ...app.src.util.convert_utils import *

注意：这种方式需要通过包的形式运行测试，不能直接双击或用python test_convert_utils.py执行，需在项目根目录运行：

python -m tests.unit.util.test_convert_utils

方法3：设置PYTHONPATH环境变量 #

在运行测试前，将项目根目录添加到PYTHONPATH环境变量中：

• Linux/macOS：

export PYTHONPATH=/绝对路径/backend-app:$PYTHONPATH

• Windows（命令提示符）：

set PYTHONPATH=C:\绝对路径\backend-app;%PYTHONPATH%

• Windows（PowerShell）：

$env:PYTHONPATH = "C:\绝对路径\backend-app;$env:PYTHONPATH"

设置完成后，直接运行测试脚本或使用pytest都能正常导入模块。

方法4：配置pytest自动识别根目录 #

如果使用pytest进行测试，在项目根目录创建pytest.ini文件，内容如下：

[pytest]
pythonpath = .

配置后，pytest会自动将项目根目录加入Python路径，测试文件中直接用绝对导入即可：

from app.src.util.convert_utils import *

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