如何为参数化pytest用例在HTML报告中添加个性化描述

问题背景 #

运行参数化pytest测试时，HTML报告中所有参数化用例的描述都是统一的测试函数文档字符串，无法区分不同参数实例。需要将每个用例的测试ID或自定义唯一文本（如来自文件的标识）添加到报告的描述区域，让每个用例的描述更具辨识度。

解决方案 #

方法1：利用pytest钩子函数修改报告显示内容 #

通过pytest_report_teststatus钩子函数，可以在测试报告生成时，自动将测试ID拼接进描述字段。在项目根目录创建conftest.py文件，添加以下代码：

def pytest_report_teststatus(report, config):
    if report.when == 'call':
        # 从测试节点ID中提取参数化测试ID
        test_id = report.nodeid.split('[')[-1].rstrip(']')
        # 获取原测试函数的文档字符串
        original_doc = report.function.__doc__ or ""
        # 拼接生成新的描述内容
        report.description = f"{original_doc.strip()} (测试ID: {test_id})"

运行原测试命令生成HTML报告后，每个用例的描述会自动带上对应的测试ID。

方法2：动态生成带参数信息的测试函数文档字符串 #

如果希望直接为每个参数化实例生成专属文档字符串，可以自定义参数化装饰器，结合测试数据动态修改测试函数的docstring：

import pytest
import json
from deepdiff import DeepDiff

def load_json_file(filename) -> list:
    """ Load the data from the given json file, return a list. """
    with open(filename, 'r') as openfile:
         json_object = json.load(openfile)
    return list(json_object.items())

def data_from_browser():
    return load_json_file('given_data.json')

def desired_data():
    return load_json_file('desired_data.json')

def list_of_ids():
    return ["set1", "set2", "set3"]

# 自定义参数化装饰器，为每个实例生成专属docstring
def parametrize_with_docstring(argnames, argvalues, ids=None):
    def decorator(func):
        original_doc = func.__doc__ or ""
        # 遍历参数化数据和ID，逐个生成实例的描述
        for args, test_id in zip(argvalues, ids):
            # 可根据测试数据生成更具体的描述，比如提取校验字段名
            checked_field = args[0][0]
            func.__doc__ = f"{original_doc.strip()}\n测试ID: {test_id}\n校验字段: {checked_field}"
            func = pytest.mark.parametrize(argnames, [args], ids=[test_id])(func)
        return func
    return decorator

@parametrize_with_docstring("given, expected", list(zip(desired_data(), data_from_browser())), ids=list_of_ids())
def test_timedistance_v0(given, expected):
    """ General docstring for the parametrized test. """
    assert given[0] == expected[0] # 校验字段名
    dict_diff = DeepDiff(given[1],  expected[1]) # 校验字段值
    assert len(dict_diff) == 0, '给定值与期望值不匹配.'

这种方式会让每个参数化测试实例拥有独立的文档字符串，HTML报告将直接显示该个性化描述。

方法3：自定义pytest-html模板实现灵活展示 #

如果需要更个性化的报告布局，可以修改pytest-html的默认模板：

1. 找到pytest-html的默认模板（通常在site-packages/pytest_html/resources/templates/report.html），复制到项目目录并重命名为custom_report.html
2. 修改模板中显示描述的代码块，添加测试ID展示：

<div class="description">
  {% if report.description %}
    {{ report.description }}
  {% endif %}
  {% if report.nodeid %}
    <br>测试ID: {{ report.nodeid.split('[')[-1].rstrip(']') }}
  {% endif %}
</div>

3. 运行测试时指定自定义模板：

pytest -v -s test_my_param.py --html="reports/report_param.html" --template=custom_report.html

内容的提问来源于stack exchange，提问作者Michala