Allure报告需pytest插件生成JSON数据并用allure-commandline渲染，二者版本须兼容；执行时必须指定--alluredir路径，报告生成后通过allure serve启动，且allure-results目录不可手动修改或混用。
Allure 报告本身不依赖 Python 运行时生成，它只消费 JSON 格式的测试结果；所谓“结合 Allure”，本质是让 pytest（或其他测试框架）在执行时输出符合 Allure 规范的中间结果，再用 allure-commandline 命令行工具生成静态 HTML 报告。直接 pip install allure-pytest 并不等于报告自动出现——漏掉生成步骤或路径配置错误，就会看到空报告、404 或 “No data to display”。
安装与基础命令链必须配齐
缺一不可：pytest 插件负责产出数据，allure-cli 负责渲染。两者版本需兼容（例如 allure-pytest 2.13.x 对应 allure-commandline 2.23+）。
-
pip install allure-pytest—— 让 pytest 知道怎么写 JSON 结果 -
brew install allure-commandline（macOS）或从 GitHub Releases 下载二进制包并加入 PATH —— 否则运行allure serve会报 command not found - 执行测试时必须加
--alluredir参数指定输出目录，例如：pytest test_login.py --alluredir=./allure-results - 生成并打开报告：运行
allure serve ./allure-results（注意路径要和--alluredir一致）
添加用例标题、步骤、附件必须用装饰器或 fixture
Allure 不解析函数名或 docstring 自动转标题，所有元信息都要显式声明。没加 @allure.title 就默认显示 test_ 开头的函数名，中文乱码、下划线难读；不调用 allure.attach 就无法嵌入截图或日志。
- 标题：用
@allure.title("用户登录成功")替代函数名，支持中文和占位符，如@allure.title("登录 {user}") - 步骤：用
with allure.step("输入用户名"):包裹操作块，嵌套 step 会自动形成折叠流程图 - 附件：截图用
allure.attach(driver.get_screenshot_as_png(), name="异常截图", attachment_type=allure.attachment_type.PNG)；文本日志用allure.attach("request: POST /api/login", name="请求详情", attachment_type=allure.attachment_type.TEXT) - 别在
conftest.py里全局 import allure —— pytest 会因找不到 fixture 报错；应在具体 test 文件或自定义 fixture 中导入
allure-results 目录内容不能手动删也不能混用
每次运行 pytest --alluredir 都会向目标目录追加 JSON 文件（每个测试方法一个），但 Allure 渲染时会全量读取整个目录。如果中途删了部分 JSON、或把两次不同环境的执行结果塞进同一个目录，会出现用例数对不上、状态错乱、甚至 report 启动失败。
立即学习“Python免费学习笔记（深入）”；
- 建议每次执行前清空目录：
rm -rf ./allure-results && pytest --alluredir=./allure-results - CI 场景下，用时间戳隔离：
--alluredir=./allure-results-$(date +%s) - 不要把
allure-results提交到 Git —— 它是构建产物，不是源码；.gitignore 加一行allure-results*/ - JSON 文件名含随机 UUID，不可重命名，否则 allure serve 会跳过该用例
最常卡住的地方不是代码写法，而是 allure-commandline 版本和 allure-pytest 不匹配，或者 --alluredir 指向了一个有残留旧文件但权限异常的目录——此时 allure serve 可能静默失败，浏览器打不开，也无报错提示。遇到空白页，先检查控制台是否打印 “Generating report to…” 和端口监听日志，再确认目录下是否有非零字节的 JSON 文件。
