只需安装 allure-pytest，它作为 pytest 与 allure 报告的唯一 python 桥梁生成 json 数据；pytest-allure-adaptor 已废弃，allure-commandline 需单独安装 java cli 工具。

直接装 allure-pytest 就够了，不用装 pytest-allure-adaptor（已废弃）或 allure-commandline（命令行工具需单独安装，不是 Python 包）。

为什么只装 allure-pytest？

它负责让 pytest 在运行时生成 Allure 兼容的原始数据（JSON 格式），是连接 pytest 和 Allure 报告的唯一 Python 层桥梁。旧版 pytest-allure-adaptor 不支持 Allure 2.x 的新特性，且已停止维护；allure-commandline 是 Java 写的 CLI 工具，必须独立安装，不能用 pip install 装。

常见错误现象：
• 安装了 pytest-allure-adaptor 后报 ImportError: No module named 'allure'
• 运行 pytest --alluredir=report 没反应、无文件生成 —— 很可能是插件没装对或版本冲突

• 正确命令：pip install allure-pytest
• 验证是否生效：pytest --help | findstr alluredir（Windows）或 pytest --help | grep alluredir（macOS/Linux），能看到该参数说明即成功
• 注意版本兼容性：Allure 2.13+ 对应 allure-pytest>=2.10.0；若用 Python 3.12+，建议选 allure-pytest>=2.13.5 避免 pydantic 冲突

--alluredir 参数必须显式指定路径

它不默认写入当前目录，也不接受相对路径缩写（如 --alluredir report 可能被误解析）。路径必须存在或可自动创建，但建议提前建好，避免权限或路径空格导致静默失败。

python学习

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

下载

• 推荐写法：pytest --alluredir=./allure-results（Linux/macOS）或 pytest --alluredir=.\allure-results（Windows）
• 避免写法：pytest --alluredir=report/（末尾斜杠在某些 shell 下引发异常）、pytest --alluredir="my report"（含空格未引号包裹，Windows CMD 下大概率失败）
• 生成后检查：ls ./allure-results 应看到一堆 *.json 文件，至少一个非空文件；全为空或只有 .lock 文件，说明测试根本没跑进去（比如文件名拼错、pytest 没识别到 test_*.py）

allure CLI 工具必须单独安装，且 PATH 要配对

allure-pytest 只管“写数据”，真正“读数据并渲染 HTML”的是 allure 命令行程序（Java 实现）。它不在 Python 生态里，不能靠 pip 装完就用。

• Windows：下载 allure-2.21.0.zip（2026 年最新稳定版），解压后把 allure-2.21.0\bin 加进系统 PATH，重启终端后运行 allure --version 确认
• macOS：用 brew install allure 最省事；若用 curl 手动装，注意 allure 脚本里硬编码的 JAVA_HOME 路径可能指向已卸载的 JDK
• 常见卡点：'allure' is not recognized（PATH 没生效）、Could not find or load main class io.qameta.allure.CommandLine（JRE 版本太低，Allure 2.20+ 需 JDK 11+）

生成报告时 --clean 不是可选项，是必选项

重复执行 allure generate 时不加 --clean，旧报告资源（JS/CSS/图片）会残留，新 JSON 数据可能被旧缓存覆盖，导致页面空白、图表错乱、用例数不更新等诡异问题。

• 安全写法：allure generate ./allure-results -o ./allure-report --clean
• 别图省事写成：allure generate ./allure-results -o ./allure-report（尤其在 CI 中，历史残留极易引发误判）
• 如果只想快速预览，用 allure serve ./allure-results 更稳妥——它每次启动都临时构建，天然隔离

最易被忽略的是：Allure 报告依赖前端资源加载，直接双击 index.html 必然白屏（浏览器禁止本地 file:// 协议跨域读取 JS）。必须用 allure serve 或 allure open 启服务，或者用 PyCharm 右键 Open in Browser（它内部起了本地服务）。这点和 pytest-html 完全不同，别凭经验跳过。

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