pytest.ini 必须放在测试文件所在目录或其任意父目录中,且优先使用离测试文件最近的那个;文件名必须为 pytest.ini、编码为 utf-8 无 bom,否则会解析失败。

pytest.ini 文件放在哪才生效
pytest 只在当前测试目录或其任意父目录中查找 pytest.ini,且**优先使用离测试文件最近的那个**。如果项目结构是 tests/ 子目录下跑测试,但 pytest.ini 放在项目根目录,它依然有效;但如果同时在 tests/ 里放了一个同名文件,根目录的就会被忽略。
常见错误现象:pytest -v 行为没变,插件也不加载——八成是文件放错了位置,或者名字写成了 pyproject.toml 或 setup.cfg 却没配对的 section。
- 必须命名为
pytest.ini(不能是pytest.conf或其他) - 文件编码必须是 UTF-8,BOM 头会导致解析失败,报错类似
ConfigError: unexpected section 'pytest' - 如果用了
pyproject.toml,得确保有[tool.pytest.ini_options]段,且格式严格(比如字符串值要加引号)
怎么用 pytest.ini 控制默认命令行参数
把常用参数写进 pytest.ini 的 [tool:pytest] section 下,能省掉每次敲一堆 flag。比如跳过慢测试、固定 Python 版本警告、指定 markers,全可以固化。
注意:ini 文件里的布尔值只能写 true/false(小写),不能写 True 或 1,否则会静默失效。
[tool:pytest] addopts = -xvs --tb=short --strict-markers testpaths = tests python_files = test_*.py python_classes = Test* python_functions = test_*
-
addopts是核心,所有值会被拼到命令行最前面,所以它后面的选项可被用户显式传入的覆盖(比如你设了-v,但运行时加-q,最终以-q为准) -
testpaths和python_*系列控制发现范围,避免误扫非测试代码,也影响pytest --collect-only输出 - 不要在
addopts里写--junitxml这类带路径的选项,除非路径是绝对或相对于 pytest 执行目录稳定的
插件启用和配置必须匹配版本与命名
pytest 插件不是装完就自动生效的,很多需要显式启用或配置。比如 pytest-cov 要在 ini 里开 addopts = --cov=src,而 pytest-asyncio 得声明 asyncio_mode = auto 才能让 async def test_* 被识别。
图片提示词生成器?不止如此。 马甲系统 —— 把脑海中的画面,翻译成AI能理解的专业表达。 用得越多,它越懂你:首次需要多问几句确认方向,用久了几乎一说就懂。 用得越多,它越快:缓存机制让后续对话越来越省。 RAG进化:成功案例持续入库,越跑越聪明。 输入「新手指南」查看完整功能介绍
容易踩的坑是插件名和配置项名不一致:例如 pytest-xdist 对应的配置项是 looponfail 或 numprocesses,但如果你写成 xdist_numprocesses 就完全无效。
- 插件配置项必须查对应文档,不能靠猜;比如
pytest-timeout用timeout和timeout_method,而不是pytest_timeout_* - 多个插件共存时,
addopts顺序有时会影响行为(如--cov放太后面可能漏统计) - 某些插件(如
pytest-benchmark)需额外安装才能解析其配置项,否则 pytest 启动直接报unknown option
pytest.ini 和 pyproject.toml 混用时的优先级陷阱
如果项目里同时存在 pytest.ini 和 pyproject.toml,pytest **只认其中一个**:它按顺序查找 pytest.ini → pyproject.toml → setup.cfg,找到第一个就停,不会合并。
这意味着:你在 pyproject.toml 里写了 [tool.pytest.ini_options],但根目录又不小心留了个空的 pytest.ini,那 toml 里的所有配置都作废。
- 用
pytest --help最后一行看“config file”路径,确认实际加载的是哪个 - 检查是否真有冲突文件:
find . -name "pytest.ini" -o -name "pyproject.toml" | xargs ls -l - 团队协作时,建议统一用
pyproject.toml(现代 Python 项目标准),但得确保 CI 和本地环境 pytest 版本 ≥ 6.0
复杂点在于,有些插件只支持 toml 配置,有些只读 ini,还有些两者都支持但字段名不同——别指望“写一次,到处生效”。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!










