unittest执行discover tests报ModuleNotFoundError的路径配置问题

根因说明 #

执行python3 -m unittest discover tests时，Python模块搜索路径sys.path默认不会自动包含项目根目录project，因此测试文件中导入common_utils相关模块时无法找到对应包。
而未指定tests参数的discover命令默认以当前执行目录为搜索起点，当前目录会自动加入sys.path，因此可以正常执行。

方案1：修改VSCode测试配置（推荐） #

直接修改VSCode的unittest运行参数，避免默认指定tests为搜索起点：

1. 在项目根目录创建.vscode/settings.json文件（已存在则直接修改）
2. 加入以下配置：

{
    "python.testing.unittestEnabled": true,
    "python.testing.pytestEnabled": false,
    "python.testing.unittestArgs": [
        "-v",
        "-s",
        ".",
        "-p",
        "test_*.py"
    ]
}

该配置将unittest的搜索起点改为项目根目录，和手动执行python3 -m unittest discover的逻辑完全一致，无需修改其他代码。

方案2：配置PYTHONPATH环境变量 #

如果需要保留discover tests的调用逻辑，可以通过配置环境变量把项目根目录加入模块搜索路径：

1. 在项目根目录创建.env文件
2. 写入以下内容：

PYTHONPATH=${PYTHONPATH}:./

3. 若VSCode未自动识别env文件，可在.vscode/settings.json中补充配置：

{
    "python.envFile": "${workspaceFolder}/.env"
}

方案3：测试文件内动态添加搜索路径 #

在测试文件开头手动将项目根目录加入sys.path，以tests/orders/test_orders.py为例：

import sys
from pathlib import Path
# 向上追溯3级路径，从test_orders.py所在目录定位到project根目录
sys.path.append(str(Path(__file__).parent.parent.parent.resolve()))

# 后续再导入common_utils
from common_utils.crawler import *

方案4：将项目配置为可安装包 #

在项目根目录添加pyproject.toml配置文件，将项目打包为可编辑安装的包，一次配置永久生效：

1. 新建pyproject.toml写入基础配置：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "your-project-name"
version = "0.1.0"
packages = ["main_app", "microservice1", "microservice2", "common_utils"]

2. 执行安装命令：

pip install -e .

安装完成后，当前Python环境下任意位置都可以直接导入common_utils等模块，不存在路径问题。

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