test/ 应与 src/ 平级——这是最稳妥的选择，可避免导入错误和 CI 不稳定；需严格遵循 pytest 命名规则（test_.py、test_函数）、路径映射（test/ 内部模仿 src/ 层级结构但不复制文件）、conftest.py 作用域规则及禁止相对导入。
test/ 目录该不该和 src/ 平级？
绝大多数项目用 src/ 放生产代码，测试目录放哪，直接决定导入是否出错、CI 是否稳定。平级（test/ 与 src/ 同级）是最稳妥的选择——Python 的 pytest 默认从当前工作目录开始搜 test_*.py 或 *_test.py，且能自然避开 src/ 下的包导入冲突。
常见错误现象：ModuleNotFoundError: No module named 'myapp'，本质是 Python 解释器没把 src/ 加进 sys.path，而你在测试里写了 from myapp import foo。
- 用
src/结构时，运行测试必须在项目根目录下执行pytest test/，不能进到test/目录里再跑 - 别在
test/里写__init__.py—— 它不是包，只是 pytest 的扫描目录 - 如果非要用
python -m pytest，确保当前目录是项目根，否则src/不会被识别为可导入源
test/ 内部要不要模仿 src/ 的包结构？
要，但只模仿层级，不复制文件。比如 src/myapp/utils.py 对应的测试放在 test/test_utils.py；若 src/myapp/api/v1/endpoints.py，测试就放 test/api/v1/test_endpoints.py。这样路径映射清晰，改一个模块时，一眼知道去哪补测试。
容易踩的坑：有人把测试文件塞进 src/myapp/tests/，结果 CI 打包时把测试代码一起打进 wheel，体积变大，还可能触发误导入。
立即学习“Python免费学习笔记（深入）”；
- 测试目录结构只服务于人眼定位和工具扫描，pytest 不依赖它做导入解析
- 不要求每个
.py都有对应测试文件，空目录（如test/api/v2/）可以存在，只要没test_*.py，pytest 就忽略 - 避免在测试文件里用相对导入（如
from ..utils import helper），它依赖运行时的__package__，极易崩
conftest.py 放哪？为什么不能乱放？
conftest.py 是 pytest 的配置钩子文件，作用域由它所在目录决定：放在 test/ 根下，整个测试套件都可见；放在 test/api/ 下，就只对 test/api/** 里的测试生效。放错位置，fixture 就找不到，或者意外覆盖。
典型错误现象：Fixture 'db_session' not found，查半天发现 conftest.py 在 test/unit/，但测试跑在 test/integration/，压根没加载。
- 全局 fixture（如
tmp_path增强、日志捕获）统一放test/conftest.py - 模块级 fixture（如某组 API 共用的 mock server）放在对应子目录的
conftest.py，别往上提 - 一个目录下最多一个
conftest.py，重复会导致 pytest 加载失败或行为不可预测
测试文件命名和函数名怎么起才不被 pytest 忽略？
pytest 只认两种默认模式：test_*.py 或 *_test.py；函数名必须是 test_* 开头。名字不对，文件就静默跳过，连报错都没有，最危险。
常见错误现象：写了 check_login_flow.py，里面函数叫 verify_login()，运行 pytest 后显示 0 tests collected，人傻了。
- 文件名必须含
test前缀或后缀，推荐统一用test_*.py（更符合直觉） - 函数名必须是
test_开头，后面接描述性名字，如test_user_creation_with_valid_email，别缩写成test_create_user—— 模糊的命名会让失败时多花三倍时间定位 - 类名也得是
Test*开头，且不能带__init__方法，否则 pytest 会跳过整个类
路径映射和命名规则看着琐碎，但一旦定下来，后续加新模块、配 CI、交接给同事，几乎不用再想“测试该放哪儿”。真正麻烦的是早期图省事随便放，等项目长到二十个模块，重构测试结构比重写部分业务还累。
