pytest-html默认不显示docstring，需确保函数首行为有效文档字符串并升级插件至≥3.2.0，配合--html和-v参数启用描述渲染。
pytest生成HTML报告时为什么测试用例不显示docstring？
默认情况下，pytest-html 插件只展示测试函数名（如 test_user_login），不会自动提取 """文档字符串""" 作为用例描述。这不是bug，是插件默认行为——它把 __doc__ 当作可选元信息，不主动渲染。
要让报告里出现自然语言描述，得手动启用描述支持：
- 安装带扩展能力的插件：
pip install pytest-html（确保 ≥3.2.0） - 运行时加参数：
pytest --html=report.html --self-contained-html -v - 关键一步：在测试函数开头写 docstring，且必须是**模块级缩进下的第一段字符串**，不能被注释或空行隔开
示例有效写法：
def test_create_order():
"""用户下单成功，库存扣减并生成订单号"""
assert create_order(...) is not None如果写成这样就无效：
立即学习“Python免费学习笔记（深入）”；
def test_create_order():
# 这不是docstring
"""用户下单成功...""" # 被注释挡住，__doc__ 为 None
assert ...如何让pytest-html报告包含用例集（test suite）层级结构？
原生 pytest-html 不识别“测试集”概念，它按文件+类+函数扁平展开。所谓“用例集”，实际是靠 Python 的 class 或目录结构组织的，报告里想体现层级，只能靠命名规范 + 插件配置。
实操建议：
- 用
class封装逻辑相关的测试，类名带业务含义，如TestPaymentFlow，它的 docstring 会被插件读取并显示在报告的“Suite”栏 - 确保每个测试文件以
test_*.py命名，pytest 才能自动发现 - 避免在
conftest.py里定义测试函数，它们不会出现在 HTML 报告的用例列表中 - 如果需要跨文件聚合，改用
pytest --tb=short -k "smoke"配合标签（@pytest.mark.smoke），再通过--html输出，报告会按 marker 分组显示
导出的HTML报告打不开或样式错乱怎么办？
常见原因是用了 --self-contained-html 但输出路径含中文、空格或特殊字符，或者浏览器直接双击打开 file:// 协议导致 JS/CSS 加载被拦截。
稳定做法：
- 输出路径用纯英文、无空格：
pytest --html=./reports/test_report.html --self-contained-html - 别双击打开，而是用 Python 起个临时服务：
python -m http.server 8000，然后访问http://localhost:8000/reports/test_report.html - 如果报告里“Passed/Failed”数字对不上，检查是否漏了
-v参数——没它，部分跳过（skip）或预期失败（xfail）的用例可能不计入统计 - 注意
pytest-html默认不捕获日志（print或logging），需额外加--capture=no或配置log_cli=true在pytest.ini中
想导出纯文本文档型报告（非HTML）有哪些轻量选择？
如果目标是生成 Word/PDF/Markdown 文档用于评审或归档，硬套 pytest-html 反而绕路。更直接的方式是利用 pytest 的标准输出重定向 + 简单解析。
推荐组合：
- 用
pytest --tb=short -v --capture=no > report.txt 2>&1直接保存终端结果，清晰反映执行顺序和失败堆栈 - 配合
pytest --junitxml=report.xml，再用 Python 脚本读取 XML 解析出用例名、状态、耗时，转成 Markdown 表格（几行xml.etree.ElementTree就够） - 避免用
pytest-docs这类冷门插件——维护停滞、Python 3.11+ 兼容差，且依赖 Sphinx，小项目没必要引入整套文档工具链
真正卡住的地方往往不是格式，而是 docstring 写得像代码注释（“调用了 create_user”），而不是测试意图（“验证邮箱重复时返回 400 错误”）。报告再漂亮，描述不准确也没法当文档用。
