推荐采用tests/顶层目录结构，镜像源码层级，如src/utils/helpers.py对应tests/utils/test_helpers.py；conftest.py按作用域分层放置，tests/下建议保留空__init__.py确保导入安全。

Python单元测试的目录结构没有强制标准，但合理的组织方式能显著提升可维护性、可读性和CI/CD集成效率。核心原则是：测试代码与被测代码分离、层级对应、命名清晰、避免循环依赖。

常见且推荐的测试目录结构

最主流、被pytest和大多数工具默认支持的是 tests/ 顶层目录方式：

• 项目根目录下新建 tests/ 文件夹（与 src/ 或 myproject/ 同级）
• tests/ 内部结构尽量镜像源码结构
• 例如源码为 src/utils/helpers.py，对应测试写在 tests/utils/test_helpers.py
• 每个测试文件以 test_ 开头，函数名也以 test_ 开头（pytest自动识别）

为什么不用 unittest.TestCase 子目录？

不建议把所有测试塞进 tests/test_something.py 这类扁平结构里。原因包括：

python学习

Python 编程学习助手 skill，面向零基础用户。 当用户表达以下意图时触发： - 学习 Python 基础概念（变量、数据类型、循环、函数、类等） - 请求 Python 练习题或测验 - 请求审查或调试 Python 代码 - 请求 Python 项目实战指导（爬虫、数据分析、Web 开发等入门项目） - 泛化表述如"教我 Python""我想学编程""Python 怎么写""帮我学 Python" 此 skill

下载

• 随着模块增多，单个文件膨胀难定位
• 无法按功能/模块快速运行子集（如 pytest tests/api/）
• 不利于团队分工（不同人负责不同模块的测试）
• mock或fixture复用困难，容易跨模块污染

如何处理共享 fixture 和 conftest.py？

conftest.py 是pytest的配置枢纽，按作用域分层放置更安全：

• 项目级共享：放在 tests/conftest.py（全局生效）
• 模块级共享：放在 tests/api/conftest.py（仅对 tests/api/ 及子目录有效）
• 避免在 src/ 中放 conftest.py —— 测试配置不应混入生产代码
• fixture 名称要有业务含义，比如 @pytest.fixture def sample_user() 而不是 obj1

是否需要 __init__.py？

从 Python 3.3+ 起，tests/ 目录本身不需要 __init__.py 就能被识别为包；但如果你在测试中用到了相对导入（比如 from ..src import mymodule），就需要它。更稳妥的做法是：

• 在 tests/ 下放空的 __init__.py（显式声明为包）
• 在 setup.py 或 pyproject.toml 中通过 packages 或 find_packages() 明确排除 tests/
• 确保 PYTHONPATH 或 -m pytest 运行方式不意外把 tests/ 当成源码包导入

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！