Python自动化测试脚本怎么生成Allure可视化报告

Python自动化测试脚本生成Allure可视化报告，需要把“结果采集”和“网页渲染”分成两步完成：先在Python虚拟环境中安装pytest与allure-pytest插件，运行测试脚本并传入--alluredir参数，将每条用例的执行状态、耗时与报错信息保存为JSON和文本格式的结果文件；再调用系统中的Allure命令行工具（依赖Java运行环境），通过allure serve或allure generate将这些原始数据转换为带图表、步骤树和附件的HTML网页报告。

一、为什么只装Python库无法直接得到HTML网页

初次配置Allure时，最常见的困惑是：已经用pip install allure-pytest安装了插件，为什么执行完脚本后找不到.html文件，目录里只有一堆文件名由随机字符组成的.json文件。这是因为Allure采用了跨语言的解耦设计，把“测试框架适配器”和“报告生成器”拆成了两个独立组件。

在Python侧，allure-pytest只是一个监听插件。它在pytest执行测试函数的过程中挂钩各个生命周期节点，记录哪个用例通过、哪个断言失败、耗时多少毫秒，并在指定目录写出符合Allure标准的原始数据文件。它本身不包含任何前端页面模板或图表渲染代码。

真正的HTML页面合成由独立的Allure Commandline（命令行工具）完成。这个命令行工具基于Java开发，负责读取目录里的JSON、TXT和附件文件，汇总统计通过率、趋势图与分类树，最终输出完整的单页Web应用。因此，系统里必须同时具备Python采集插件和Allure命令行工具，缺一不可。

二、准备运行环境与安装双端组件

在编写测试代码前，需要先打通Python插件、Java运行环境和Allure命令行工具三项依赖。如果使用的是原有的自动化测试项目，建议在项目的虚拟环境中操作。

1. 安装pytest与allure-pytest插件

打开终端（Windows下可使用PowerShell或CMD），激活Python虚拟环境后，安装测试框架与Allure适配器插件：

pip install pytest allure-pytest

2. 确认Java环境并安装Allure命令行工具

由于Allure命令行工具需要Java运行环境支持，先在终端运行java -version检查是否已安装Java 8或更高版本。确认Java可用后，根据操作系统选择安装Allure命令行工具的方式：

• macOS系统：使用Homebrew直接安装，在终端执行brew install allure，Homebrew会自动完成路径配置。
• Windows系统：若已安装Scoop包管理器，可执行scoop install allure；若手动安装，可从Allure官方GitHub Releases页面下载allure-commandline的ZIP压缩包，解压到本地固定目录（例如D:\tools\allure-2.29.0），然后将解压目录下的bin文件夹路径（即D:\tools\allure-2.29.0\bin）添加到系统环境变量Path中。
• Linux系统（Ubuntu/Debian）：解压官方tgz包到/opt/allure，并通过ln -s /opt/allure/bin/allure /usr/local/bin/allure创建软链接。

配置完成后，必须重新打开一个新的终端窗口使环境变量生效，随后执行以下命令验证：

allure --version

2.29.0

只要终端正常打印出版本号，就说明命令行渲染工具已经就绪。

三、从Python测试脚本生成Allure报告的完整步骤

环境就绪后，创建一个干净的工作目录（例如allure_demo），按“编写脚本→采集结果→渲染网页”三步走完标准流程。

步骤1：编写基础测试脚本

在allure_demo目录下新建文件test_order.py。即便先不添加任何Allure专属装饰器，allure-pytest也能自动收集pytest的用例执行结果。这里我们准备一条通过用例和一条失败用例，方便在报告中对比显示效果：

def calc_discount(price, rate):
    return round(price * rate, 2)


def test_normal_discount():
    """验证常规商品九折计算是否正确"""
    actual = calc_discount(100, 0.9)
    assert actual == 90.0


def test_vip_discount_fail():
    """演示断言失败在Allure报告中的展示效果"""
    actual = calc_discount(100, 0.75)
    assert actual == 80.0, f"预期折后价为80.0，实际计算结果为{actual}"

步骤2：运行pytest并指定结果输出目录

在allure_demo目录下打开终端，执行pytest并通过--alluredir参数指定原始结果数据的存放文件夹（如./allure-results）。建议同时加上--clean-alluredir参数，用于在每次运行前自动清空该目录下的旧数据，防止历史执行记录混入本次报告：

pytest test_order.py --alluredir=./allure-results --clean-alluredir

============================= test session starts ==============================
collected 2 items

test_order.py .F                                                          [100%]

=================================== FAILURES ===================================
____________________________ test_vip_discount_fail ____________________________
    def test_vip_discount_fail():
        actual = calc_discount(100, 0.75)
>       assert actual == 80.0, f"预期折后价为80.0，实际计算结果为{actual}"
E       AssertionError: 预期折后价为80.0，实际计算结果为75.0
=========================== short test summary info ============================
FAILED test_order.py::test_vip_discount_fail - AssertionError: 预期折后价为80.0...
========================= 1 failed, 1 passed in 0.08s ==========================

执行完毕后，查看当前目录下的allure-results文件夹，会看到生成了多个形如a3f18c...-result.json的文件。每个JSON文件对应一条测试用例的详细执行记录。

步骤3：把结果数据渲染为可视化网页

拿到./allure-results目录后，Allure提供了两种生成和查看报告的方式，分别对应“本地快速调试”和“持久化存档/持续集成”两种场景：

方式A：使用allure serve即时预览（适合本地编写调试脚本）

在终端直接指向结果目录运行：

allure serve ./allure-results

该命令会在系统的临时目录中生成HTML文件，自动启动一个内置的Jetty本地Web服务器，并自动调用系统默认浏览器打开报告地址（例如http://192.168.1.10:54321/index.html）。在终端按下Ctrl + C即可停止该Web服务。

方式B：使用allure generate生成静态报告目录（适合归档或Jenkins集成）

如果需要将生成的HTML文件保存到指定文件夹，使用generate子命令，并通过-o指定输出目录，通过--clean覆盖旧的HTML报告目录：

allure generate ./allure-results -o ./allure-report --clean

Report successfully generated to ./allure-report

allure open ./allure-report

四、在Python脚本中定制报告层级、步骤与附件

只运行默认脚本时，Allure报告只能展示文件名、函数名和通过状态。在实际项目中，测试人员往往需要知道“这条用例属于哪个业务模块”“在哪一步操作失败”“失败时的接口响应或页面截图是什么”。通过在Python代码中引入import allure并使用装饰器，可以把这些上下文直接映射进报告对应的面板中。

常用定制装饰器与完整代码示例

改造前面的test_order.py，加入模块分级、中文标题、严重级别、步骤拆解以及JSON数据附件。完整代码如下：

import json
import allure


def calc_discount(price, rate):
    return round(price * rate, 2)


@allure.epic("电商交易中心")
@allure.feature("订单计价模块")
@allure.story("会员折扣计算")
@allure.title("验证普通会员九折结算金额正确")
@allure.severity(allure.severity_level.CRITICAL)
def test_normal_discount():
    order_payload = {"order_id": "ORD20261104", "origin_price": 100, "rate": 0.9}

    with allure.step("步骤1：准备订单原始入参并记录报文"):
        allure.attach(
            body=json.dumps(order_payload, ensure_ascii=False, indent=2),
            name="订单请求参数",
            attachment_type=allure.attachment_type.JSON,
        )

    with allure.step("步骤2：调用折扣计算函数"):
        actual = calc_discount(order_payload["origin_price"], order_payload["rate"])

    with allure.step(f"步骤3：校验折后金额是否等于 90.0（实际值：{actual}）"):
        assert actual == 90.0

如果是Selenium或Playwright等UI自动化脚本，还可以在断言失败或关键步骤中使用allure.attach.file("./error.png", name="失败页面截图", attachment_type=allure.attachment_type.PNG)将本地截图直接嵌入步骤下方，无需在排查问题时再去翻找服务器日志目录。

把运行参数写入pytest.ini简化日常执行

每次在终端手敲--alluredir=./allure-results --clean-alluredir容易遗漏。可以在项目根目录下新建pytest.ini配置文件，将参数固定下来：

[pytest]
addopts = -vs --alluredir=./allure-results --clean-alluredir
testpaths = .

保存后，后续在项目根目录下只需输入pytest，就会自动清理旧数据并将新结果写入./allure-results。

五、常见问题与排查方法

如果按照步骤执行后报告未能正常显示，可以根据具体现象按以下三类原因定位：

六、命令与配置速查总结

日常在Python自动化测试中使用Allure，只需把握住“采集参数”“预览命令”与“装饰器分层”三个核心环节。下图汇总了从环境校验到报告产出的关键命令与装饰器组合，可作为配置时的核对清单：