如何在pytest HTML报告中为每个测试显示自定义描述

核心问题分析 #

你直接给request.node.report_custom_description赋值无效——因为request.node是测试项（item）对象，而HTML报告读取的是测试报告（report）对象的属性，两者并非同一实例。另外必须保留默认空值，否则未设置描述的测试执行时会因找不到属性报错。

正确实现步骤 #

1. 配置conftest.py钩子函数 #

在测试目录的conftest.py中添加以下代码，负责添加自定义列、将描述传递到报告对象：

import pytest

# 给HTML报告添加自定义描述表头
def pytest_html_results_table_header(cells):
    # 插入自定义列到第3列（可根据需求调整索引位置）
    cells.insert(2, '<th>测试描述</th>')

# 给每一行测试结果填充自定义描述
def pytest_html_results_table_row(report, cells):
    # 从report对象获取描述，默认空字符串避免报错
    desc = getattr(report, 'test_description', '')
    cells.insert(2, f'<td>{desc}</td>')

# 将测试项的描述传递给测试报告对象
@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    report = outcome.get_result()
    # 读取测试项的自定义描述，赋值给report
    report.test_description = getattr(item, 'test_description', '')

2. 两种设置测试描述的方式 #

方式一：使用Fixture（适合动态生成描述）

在conftest.py中添加fixture用于设置描述：

@pytest.fixture
def set_test_desc(request):
    def _set_desc(desc):
        request.node.test_description = desc
    return _set_desc

测试函数中调用该fixture：

# test.py
def test_login(set_test_desc):
    set_test_desc("登录测试：验证账号密码正确时可正常登录")
    # 测试逻辑代码
    assert True

def test_username_input(set_test_desc):
    set_test_desc("用户名输入测试：验证特殊字符输入限制")
    # 测试逻辑代码
    assert True

方式二：使用Pytest Mark（适合静态固定描述）

直接在测试函数上标记描述，无需额外fixture：

# test.py
import pytest

@pytest.mark.test_desc("登录测试：验证账号密码正确时可正常登录")
def test_login():
    # 测试逻辑代码
    assert True

@pytest.mark.test_desc("用户名输入测试：验证特殊字符输入限制")
def test_username_input():
    # 测试逻辑代码
    assert True

同时修改conftest.py中的pytest_runtest_makereport钩子，读取mark的值：

@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    report = outcome.get_result()
    # 读取mark中的描述
    desc_mark = item.get_closest_marker("test_desc")
    report.test_description = desc_mark.args[0] if desc_mark else ""

3. 验证执行 #

运行测试并生成HTML报告：

pytest test.py --html=report.html

打开report.html即可看到新增的「测试描述」列已正确显示自定义内容。

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