在Python大型项目中，随着业务模块不断膨胀，测试代码如果缺乏清晰的组织方式，很快就会变成难以维护的包袱。pytest作为主流测试框架，提供了一套基于目录与配置的约定，可以帮助团队把测试用例按照模块、场景和层级进行物理隔离与逻辑归类。
为什么需要模块化的测试目录
当项目只包含几十个函数时，把所有测试写在一个test_all.py里似乎没什么问题。但大型项目通常有十几个业务域，每个域又有模型、服务、接口等多层逻辑。如果把用户、订单、支付等模块的用例混在一起，不仅文件体积巨大，而且任何一次重构都可能牵一发而动全身。
模块化的目录结构让测试与源码形成镜像关系。开发者在修改某个功能时，能立刻定位到对应的测试文件夹，而不是在成千上万行断言中盲目搜索。同时，pytest的收集机制会递归扫描目录，合理的切分能显著减少单次运行的用例规模，配合标记还可以只跑受影响的模块。
推荐的pytest目录布局
一种经过验证的布局是在项目根目录下建立tests目录，其内部再按业务模块分子文件夹。每个子文件夹放置该模块的单元测试与集成测试，并可以拥有独立的conftest.py来声明仅在本模块生效的夹具。
例如下面是一个典型结构：
project_root/
├── src/
│ ├── user/
│ ├── order/
│ └── payment/
└── tests/
├── conftest.py
├── user/
│ ├── conftest.py
│ ├── test_models.py
│ └── test_api.py
├── order/
│ ├── conftest.py
│ └── test_service.py
└── payment/
└── test_gateway.py
根级conftest.py适合放数据库会话、全局mock等跨模块资源；而user目录下的conftest.py可以专门构造用户对象，避免其他模块误用。这种分层注入的方式降低了夹具的耦合度。
使用conftest.py共享夹具
conftest.py是pytest的特殊的配置文件，不需要显式import，框架会自动发现并加载。在大型项目中，把高频使用的夹具放在对应层级的conftest.py里，既能复用又不会污染全局命名空间。
下面代码展示了一个模块级conftest如何提供假用户数据：
import pytest
@pytest.fixture
def fake_user():
# 返回一个简单的用户字典用于测试
return {"id": 1, "name": "test_user", "role": "normal"}
@pytest.fixture
def auth_client(fake_user):
# 基于假用户构造一个已认证的客户端对象
class Client:
def get(self, path):
return {"user": fake_user, "path": path}
return Client()
在user/test_api.py中，直接使用auth_client而无需重复定义。如果将来认证逻辑变化，只需改这一处，同模块所有用例同步生效。
通过pytest.ini固化目录规则
为了避免pytest误收集到源码目录或虚拟环境中的测试文件，可以在项目根放置pytest.ini，明确指定测试路径与忽略项。
[pytest] testpaths = tests python_files = test_*.py addopts = -ra -q norecursedirs = .git venv build dist *.egg-info
上述配置把收集范围锁死在tests内，并跳过常见非代码目录。norecursedirs能防止CI机器上因扫描node_modules之类文件夹导致卡死。testpaths的存在也让新成员一眼看清测试入口。
用标记实现模块间筛选
pytest的mark机制允许给用例打标签，在模块化基础上进一步按需运行。比如只验证订单模块时，可以执行pytest -m order。
import pytest
@pytest.mark.order
def test_create_order():
assert True
@pytest.mark.user
def test_login():
assert True
配合pytest.ini里的markers声明，可避免未注册标记产生警告。这种组合让大型项目在提交前只跑关联模块，把反馈时间从分钟级压到秒级。
与CI集成的并行策略
在持续集成中，可以利用目录边界做并行拆分。例如用pytest-xdist按tests子目录分配进程，或者让不同流水线阶段负责不同模块。由于目录之间依赖已被conftest隔离，并行不会产生状态冲突。
一个简化的CI脚本片段如下：
# 阶段一：运行用户与订单模块 pytest tests/user tests/order -n 2 # 阶段二：运行支付模块 pytest tests/payment -n 1
这种切分比全量运行更节省资源，也更容易在报表中定位哪个业务域引入的失败。长期来看，目录结构本身就是一张项目健康度地图。
常见误区与规避
有的团队喜欢按测试类型而非业务模块建目录，比如unit、integration、e2e平铺在tests下，结果每个文件夹里又按模块分子目录，形成双层交叉。这样在跑某一模块时路径变得很深，且夹具难以合理摆放。
更好的做法是业务模块为一级、测试类型为二级，或直接混用类型但以文件名区分。关键原则是：让最频繁的检索维度成为目录的第一层，减少跨文件夹跳转。另外，切勿把测试数据文件散落在各处，建议在模块内建fixtures或data子目录统一托管。
通过pytest的目录约定与配置手段，大型Python项目的测试可以从杂乱无章变为层次分明。开发者在遵循结构的同时，也顺带完成了职责边界的划分，为后续重构与协作打下基础。