pytest测试需满足可发现性:文件须置于tests/或根目录,命名test_.py或_test.py且函数以test_开头;源码在src/时,应在pyproject.toml中配置pythonpath=["src"]确保导入;推荐按unit/integration/e2e分层而非与源码文件一一对应。

pytest目录结构要先满足“可发现性”,不是越深越好
pytest默认只在当前目录及子目录中递归查找test_*.py或*_test.py文件,且要求测试函数名以test_开头。如果目录嵌套过深、命名不规范,pytest根本不会执行——连报错都不会有,直接显示no tests ran。
常见错误现象:pytest运行后提示0 passed,但明明写了测试;或者只跑了一部分测试,另一些“消失”了。
- 测试文件必须放在
tests/(推荐)或项目根目录下,不能藏在src/或app/内部 - 避免用
__init__.py把tests/变成包——pytest不需要它,反而可能因导入路径干扰导致ImportError - 若项目源码在
src/下,需通过python -m pytest或配置pythonpath确保测试能导入模块,而不是靠sys.path.append()硬塞
如何让测试正确导入源码:pyproject.toml里配pythonpath比改__init__.py更稳
大型项目通常把源码放在src/下(如src/myapp/),此时测试文件tests/test_core.py想导入myapp.core,会遇到ModuleNotFoundError。这不是pytest的问题,是Python模块搜索路径问题。
最可靠的做法是在pyproject.toml中声明:
立即学习“Python免费学习笔记(深入)”;
[tool.pytest.ini_options] pythonpath = ["src"]
这样pytest启动时自动把src/加入sys.path,所有测试都能干净导入myapp.*模块。
- 不要在每个
test_*.py里写sys.path.insert(0, "../src")——路径易错、不可移植、CI里常失效 - 不要给
tests/加__init__.py并尝试相对导入,pytest不按包逻辑加载测试模块 - 如果用了
setuptools的src布局,确认setup.py或pyproject.toml中packages配置与实际结构一致,否则pip install -e .后仍可能导入失败
测试分层建议:按功能边界切,别按代码文件一对一复制
有人习惯为每个.py写一个test_*.py,比如src/myapp/db.py → tests/test_db.py。这在初期可行,但项目变大后会导致测试耦合、维护成本飙升——比如db.py重构后,几十个测试文件都要检查是否受影响。
更可持续的做法是按「能力」或「场景」组织测试,而非按「实现文件」:
-
tests/unit/:纯函数、类方法,无外部依赖(用unittest.mock或pytest-mock隔离) -
tests/integration/:连接真实DB、调用HTTP服务等,需环境准备(用pytest.fixture统一管理) -
tests/e2e/:端到端流程,如模拟API请求→DB写入→缓存更新,通常运行慢、单独触发
示例结构:
myapp/ ├── src/ │ └── myapp/ │ ├── __init__.py │ ├── core.py │ └── db.py ├── tests/ │ ├── __init__.py # 可选,仅当需跨测试共享fixture时放空文件 │ ├── conftest.py # 所有测试共用fixture、插件配置 │ ├── unit/ │ │ ├── test_core.py │ │ └── test_db.py │ ├── integration/ │ │ └── test_database_session.py │ └── e2e/ │ └── test_user_signup_flow.py
conftest.py不是万能胶水,滥用会导致测试隐式依赖
conftest.py能让同级及子目录下的测试自动访问其中定义的fixture和hook,但它不支持跨目录继承——比如tests/unit/conftest.py里的fixture,tests/integration/下的测试拿不到。
容易踩的坑:
- 在
tests/conftest.py里全局mock某个模块(如requests.get),结果所有测试都绕过了真实网络调用,集成测试失去意义 - 把数据库连接池、Redis客户端等重资源fixture设为
scope="session",但没做清理,导致后续测试读到脏数据 - 在
conftest.py里修改sys.path或os.environ,影响其他测试的环境一致性
建议原则:fixture作用域尽量窄,优先用scope="function";跨层级共享逻辑,提取成独立模块(如tests/fixtures/db.py),再显式import。
复杂点往往不在结构本身,而在测试间的状态污染和隐式约定——目录可以重命名,但fixture生命周期、模块导入路径、环境变量设置,一旦出错很难定位。


















