解决Python pytest发现不了测试文件或模块导入错误

在运行 pytest 时，开发者最常遭遇的两类异常分别是“收集不到测试用例（collected 0 items）”以及“测试文件执行时抛出 ModuleNotFoundError: No module named 'xxx'”。这两个问题往往不是被测代码本身存在语法错误，而是源于 pytest 默认的文件命名发现规则未能匹配，或者当前执行上下文未将项目根目录加载至 Python 的 sys.path 模块检索路径中。本文将针对这两类故障的具体表现拆解排查逻辑，并提供可靠的工程化解决方案。

图 1：pytest 运行时常见故障分类与诱发因素

一、排查并解决 pytest 发现不了测试文件的问题

pytest 拥有内置的测试用例自动探测机制（Test Discovery）。当在终端执行 pytest 命令后显示 collected 0 items 时，表明当前探测器未能从目录树中识别出合规的文件、测试类或测试函数。

1. 核对默认命名规则

pytest 在默认情况下遵循一套严格的正则匹配规则，任何命名脱轨都会导致用例被静默忽略：

• 测试文件名称：必须以 test_ 开头，或以 _test.py 结尾。例如 test_auth.py 或 payment_test.py 能够被发现，而 tests_user.py、testuser.py 或 check_login.py 将直接被忽略。
• 测试类命名：必须以 Test 开头（如 TestUserService），并且该类严禁定义 __init__ 构造函数。若编写了 def __init__(self):，pytest 会将其视作常规类而直接跳过。
• 测试函数与方法：必须以 test_ 为前缀，例如 def test_login_success():。如果写成 def run_test(): 或 def testUser():（大写 U 且无下划线），则不会被作为用例执行。

2. 检查命令执行目录与路径参数

默认情况下，pytest 从执行命令所在的当前工作目录（Current Working Directory）向下递归遍历。若测试文件存放在特定的子目录（如 tests/），执行时可明确指定路径：

# 显式指定目录探测用例
pytest tests/

# 仅输出收集到的用例清单，不执行测试代码，快速验证命名是否生效
pytest --collect-only

若使用了 --collect-only 仍然返回 0 items，需要检查目录是否被误置为以点号开头的隐藏文件夹（如 .tests/），pytest 默认会跳过所有隐藏目录。

图 2：pytest 测试用例发现排查流程图

3. 检查配置文件覆盖项

很多工程中存在 pytest.ini、pyproject.toml 或 setup.cfg。如果配置文件中定义了自定义规则，默认的发现逻辑会被覆盖：

# pytest.ini 示例
[pytest]
# 限制了仅在指定目录扫描
testpaths = tests
# 自定义匹配模式（若不包含 test_*.py 则默认规则失效）
python_files = test_*.py *_test.py
python_classes = Test*
python_functions = test_*

二、解决模块导入错误（ModuleNotFoundError / ImportError）

当 pytest 成功找到了测试文件，但在用例开头执行 import my_module 或 from src.app import main 时，抛出 ModuleNotFoundError: No module named '...'，其核心原因在于 Python 解释器的模块查找路径（sys.path）中未包含被引用的根目录。

图 3：sys.path 查找机制与 pytest 调用方式差异对比

方案 1：优先采用 python -m pytest 执行（即时生效）

解决导入失败最快捷、且不破坏代码的方法是在项目根目录下改用 python -m pytest：

# 推荐执行方式：确保当前工作目录被自动加到 sys.path 首位
python -m pytest

在标准命令行中直接调用 pytest 时，系统调用的是全局或虚拟环境 bin/ 目录下的控制台启动脚本；而 python -m pytest 则是通过当前指定的 Python 解释器以模块形式运行 pytest，此时 Python 解释器会自动把“当前工作目录”加入 sys.path[0]，使得 import src... 或同级包名能够被正常索引。

方案 2：在配置文件中指定 pythonpath（工程推荐）

从 pytest 7.0.0 开始，官方提供了原生的 pythonpath 配置支持。这彻底解决了不同成员在不同路径下执行 pytest 导致导入报错的问题。

如果项目使用 pytest.ini，添加如下内容：

[pytest]
# 将当前目录和 src 目录均加入 Python 模块搜索路径
pythonpath = . src

如果项目使用现代化的 pyproject.toml，配置如下：

[tool.pytest.ini_options]
pythonpath = [
  ".",
  "src"
]

方案 3：使用可编辑模式安装本地包（pip install -e .）

在遵循标准分发结构的项目（例如包含 pyproject.toml 或 setup.py）中，最根本的做法是在虚拟环境中以可编辑模式（Editable Mode）安装当前开发包：

# 激活项目的虚拟环境后执行
pip install -e .

该命令会在虚拟环境中建立对当前项目源代码的符号链接。无论在哪个目录下直接运行 pytest，解释器均能在虚拟环境的 site-packages 中寻址到你的项目包，不再依赖运行命令时的临时路径。

方案 4：在 tests 目录下放置 conftest.py 或 __init__.py

pytest 对 conftest.py 具有特殊感知：当 pytest 在目录树中发现 conftest.py 时，会自动将该文件所在目录的父级目录识别为 rootdir（根目录），并将其补充进 sys.path 中。同时，确保所有 Python 源码包目录中包含 __init__.py，以便 Python 正确识别包命名空间。

三、典型项目目录规范与配置示例

推荐采用标准的 src 目录布局，将业务代码与测试用例清晰分离：

my_project/
├── pyproject.toml        # 项目构建及 pytest 配置文件
├── src/
│   └── my_pkg/
│       ├── __init__.py
│       └── calculator.py # 核心业务代码
└── tests/
    ├── __init__.py
    ├── conftest.py       # 共享夹具与根目录锚点
    └── test_calc.py      # 测试用例文件

在 test_calc.py 中编写测试代码：

# tests/test_calc.py
from my_pkg.calculator import add

def test_add_success():
    assert add(1, 2) == 3

运行验证命令：

# 验证 1：查看收集情况
python -m pytest --collect-only

# 验证 2：完整运行测试
python -m pytest -v

图 4：pytest 故障排查与修复决策速查总结