testpaths仅控制测试发现的起始目录范围，不改变工作目录或导入路径；需配合pythonpath解决模块导入、rootdir确保路径解析基准，三者缺一不可。

Claw Code Suite (Python-Only Edition)

仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...

下载

pytest.ini 里用 testpaths 指定搜索目录，但不推荐单独依赖它

直接生效的配置项是 testpaths，但它只影响 pytest 自动发现测试的**起始目录范围**，不会改变当前工作目录或导入路径。比如你写：

[tool:pytest]
testpaths = tests unit_tests

，pytest 就只在这两个目录下递归找 test_*.py 或 *_test.py 文件。但注意：如果当前在项目根目录外执行 pytest，这些路径会以当前目录为基准拼接——容易报 FileNotFoundError: No such file or directory。

• testpaths 的值是空格分隔的相对路径，不是 glob 模式
• 它不修改 sys.path，所以测试文件里 import mypackage 仍可能失败
• 若同时存在 pythonpath 和 testpaths，前者管导入，后者管发现

必须配 pythonpath 才能让测试文件正常 import 项目代码

光有 testpaths 不解决模块导入问题。常见现象是测试文件能被找到，但一运行就报 ModuleNotFoundError。这时得加 pythonpath（注意不是 PYTHONPATH 环境变量）：

[tool:pytest]
testpaths = tests
pythonpath = src .

。pytest 会把 src 和当前目录（.）插入 sys.path[0] 前面，这样测试里就能直接 import myapp（假设 myapp/ 在 src/ 下）。

• pythonpath 值也是空格分隔的相对路径，支持 .. 回退
• 多个路径按顺序添加，前面的优先级更高
• 如果项目用了 pyproject.toml，对应字段是 [tool.pytest.ini_options.pythonpath]

避免 conftest.py 路径错位导致 fixture 不生效

testpaths 改变后，conftest.py 的作用域可能意外收缩。pytest 只在每个测试文件**向上查找最近的 conftest.py**，而这个“向上”是基于文件系统路径，不是 pythonpath。比如：

tests/
├── conftest.py      ← 这个会被 tests/unit/test_math.py 读到
└── unit/
    └── test_math.py
src/
└── myapp/
    └── __init__.py

，如果你把 testpaths 设成 tests/unit，那 tests/conftest.py 就不会被加载——因为 pytest 根本不进 tests/ 目录了。

• 要么把 conftest.py 放到 testpaths 涵盖的最顶层目录下
• 要么在 tests/unit/conftest.py 中显式 import 上层 fixture
• 别指望 pythonpath 能让 conftest.py 跨目录自动生效

真正可靠的路径控制：用 --rootdir 显式指定项目根，再配合 testpaths

很多路径问题其实源于 pytest 自动推导 --rootdir 出错。它默认取离所有测试文件最近的共同父目录，但遇到分散的 testpaths 就容易误判。强制指定最稳：

[tool:pytest]
rootdir = .
testpaths = tests unit_tests

。这样无论你在哪执行 pytest，它都以当前目录为根去解析 testpaths 和 pythonpath。

• rootdir 必须是存在的目录，且应为 Git 仓库根或 pyproject.toml 所在目录
• 命令行传 --rootdir=. 优先级高于配置文件，适合 CI 脚本临时覆盖
• 不设 rootdir 时，pytest 可能选错根目录，导致 pythonpath 解析出错

路径配置真正难的不是写对字段，而是理解 testpaths 控发现、pythonpath 控导入、rootdir 控解析基准——三者缺一不可，且各自作用域互不重叠。