安装 pytest-html 插件是前提，否则 pytest 不识别 --html 参数；基础用法为 pytest --html=report.html，需带 .html 扩展名；失败日志需配合 --self-contained-html 或 --capture=no；截图等自定义内容须通过钩子函数注入。
安装 pytest-html 插件是前提
不装这个包，pytest 默认根本不认识 --html 参数。直接运行会报错：unrecognized arguments: --html=report.html。
用 pip 安装即可：
pip install pytest-html
注意：如果项目用 venv 或 conda，确保在对应环境中安装。全局安装但测试在虚拟环境中跑，也会提示参数无效。
基础命令行生成 HTML 报告
最简用法就是加一个 --html 参数：
pytest --html=report.html
- 输出路径必须带扩展名（通常是
.html），否则报告写入失败且无提示 - 如果文件已存在，默认覆盖，不会自动重命名或备份
- 报告默认包含通过、失败、跳过、错误的统计和用例列表，但不包含控制台输出（
print或logging）
想让失败用例的日志也进报告？得加 --self-contained-html（生成单文件，含内联 CSS/JS，适合离线分享），或者配合 --capture=no 让 stdout/stderr 显示在报告里（但会干扰终端实时输出）。
失败截图和自定义内容需要手动注入
pytest-html 本身不自动截屏、不自动记录请求体或响应体。要往报告里塞额外信息，得靠钩子函数：
- 在
conftest.py里定义pytest_html_results_table_row或pytest_html_results_table_html - 比如给失败用例加截图链接，就得在
teardown阶段保存图片，并在钩子里把@#@#@#@#@#@#@#@#@#@0注入到对应行
常见漏掉的点：
- 忘记在钩子函数里加
if result.outcome != "passed"判断，导致所有用例都尝试读取不存在的截图文件，报FileNotFoundError - 路径写相对路径（如
"screenshots/test_login.png"），但报告生成时工作目录不是预期位置，链接 404
中文乱码、样式错位或 JS 不生效
本质是编码或资源加载问题：
- 确保 Python 文件保存为 UTF-8 编码（尤其
conftest.py里有中文字符串时） - 不要用
--self-contained-html+ 大量截图——单 HTML 文件可能超几 MB，浏览器打开卡顿甚至崩溃 - 如果报告里时间显示为“NaT”或为空，检查系统时区是否被 pytest 误读；可临时加
--tb=short避免 traceback 过长干扰渲染
真正麻烦的是 CI 场景：Jenkins 或 GitHub Actions 里生成的报告，常因权限或路径问题导致截图链接失效，或者 CSS 被 Content Security Policy 拦截。这时候与其硬调样式，不如改用 --html=report.html --self-contained-html 保证资源内联，再确认 HTML 文件最终被正确归档发布。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
