Allure-pytest：打造精美、强大的测试报告

Allure Framework 是一款灵活轻量级的测试报告工具，支持多种测试框架，并能生成美观且易于理解的测试报告。allure-pytest 插件则将 Allure 的强大功能无缝集成到 pytest 测试框架中，让您可以轻松创建结构化、可维护的测试报告。

1. 安装与配置

  • 安装 allure-pytest：

    pip3 install allure-pytest

  • 安装 Java（Allure 依赖 Java）：

    1. Windows 安装：

    • 下载地址：Releases · allure-framework/allure2 (github.com)
    • 选择与您的系统匹配的版本（建议选择最新的稳定版，如 allure-2.25.0.zip）。
    • 解压下载的 zip 文件。
    • 配置环境变量：将解压后的 allure/bin 目录添加到系统 PATH 环境变量中。例如：C:\Users\YourUsername\allure\bin。 注意替换 YourUsername 为你的实际用户名。

    2. Linux 安装：

    • 首先安装 Node.js (可选，推荐使用 npm 安装 allure)：
      Node.js 可以通过多种方式安装，官方推荐的安装方式见官网。

    • 使用 npm 安装 Allure (推荐):

      sudo npm install -g allure-commandline --save-dev

      如果默认安装报错，可能是网络问题。可以使用淘宝镜像源：

      npm config set strict-ssl false
npm config set registry https://registry.npm.taobao.org
sudo npm install -g allure-commandline --save-dev

      • 手动安装（如果 npm 失败）：

        # 下载 Allure 二进制文件 (与 Windows 安装类似)
wget https://github.com/allure-framework/allure2/releases/download/v2.25.0/allure-2.25.0.tgz
tar -zxvf allure-2.25.0.tgz
sudo mv allure-2.25.0 /opt/allure
sudo ln -s /opt/allure/bin/allure /usr/bin/allure  # 创建符号链接

    • 安装 JDK:

      参考下载地址：Java Downloads | Oracle
      Debian/Ubuntu:

      sudo apt-get update
sudo apt-get install openjdk-17-jdk # 或其他版本，如 openjdk-11-jdk

      CentOS/RHEL:

      sudo yum install java-17-openjdk-devel # 或其他版本

      配置 JAVA_HOME 环境变量：

      1. 找到 JDK 安装路径 (通常在 /usr/lib/jvm/ 下)。

      2. 编辑 ~/.bashrc 或 ~/.zshrc 文件，添加以下内容：

        export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64  # 替换为你的 JDK 路径
export PATH=$JAVA_HOME/bin:$PATH

      3. 运行 source ~/.bashrc 或 source ~/.zshrc 使环境变量生效。

  • 验证安装：

    allure --version

    如果成功，将显示 Allure 的版本号 (例如：2.25.0)。

2. 生成 Allure 报告

  • 配置 pytest.ini：

    在项目的 pytest.ini 文件中添加以下内容：

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

    或者，您也可以在命令行中指定：

    pytest -vs your_test_file.py --alluredir=./allure-results --clean-alluredir
    • --alluredir=./allure-results：指定 Allure 结果文件的存储目录 (例如，./allure-results)。
    • --clean-alluredir：在生成报告前清空结果目录。
    • -vs： pytest参数，用于更详细的显示控制台输出。

  • 运行测试：

    执行 pytest 命令运行您的测试用例。

  • 生成 Allure 报告：

    allure generate ./allure-results -o ./allure-report --clean
    • ./allure-results: 指定Allure结果文件路径
    • ./allure-report：指定 Allure 报告的输出目录 (例如，./allure-report)。
    • --clean：在生成报告前清空报告目录。

  • 打开 Allure 报告：

    allure open ./allure-report

    这将使用默认浏览器打开生成的 index.html 文件。 如果直接点击index.html打不开，或者显示加载失败，推荐使用此命令打开。

3. Allure 报告高级功能

  • 添加截图到报告：

    import allure
from allure_commons.types import AttachmentType

def test_with_screenshot():
    # 执行测试步骤
    # ...

    # 捕获截图
    screenshot_path = "path/to/screenshot.png"  # 替换为你的截图路径

    # 将截图添加到 Allure 报告
    allure.attach.file(screenshot_path, name="Screenshot", attachment_type=AttachmentType.PNG)

    重要: allure.attach.file 是推荐的添加附件的方式，它能正确处理文件路径和附件类型。 确保 screenshot_path 是有效的截图文件路径。 如果使用 allure.attach(path, name="Screenshot", attachment_type=AttachmentType.PNG)，注意 path参数需要是文件内容，而不是文件路径。

  • 添加视频到报告：

    import allure
from allure_commons.types import AttachmentType

def test_with_video():
    # 执行测试步骤
    # ...

    # 捕获视频
    video_path = "path/to/video.mp4"  # 替换为你的视频路径

    # 将视频添加到 Allure 报告
    allure.attach.file(video_path, name="Video", attachment_type=AttachmentType.MP4)

  • 添加环境配置信息：

    在 Allure 报告的首页 ENVIRONMENT 部分显示测试环境、版本号、测试人员等信息。

    1. 创建 environment.properties 文件：
      在 allure-results 目录中创建 environment.properties 文件。 (注意： 不是allure-report 目录!)
      重要： 确保文件编码为 UTF-8，并且文件中不能包含中文字符（否则可能导致乱码）。

      System=Linux-5.15.0-72-generic-x86_64-with-glibc2.29
PythonVersion=3.8.10
AllureVersion=2.25.0
author=yys

    2. 动态生成 environment.properties：
      为了避免手动创建和维护 environment.properties 文件，您可以编写一个函数在测试运行期间动态生成它。 这在需要包含版本号、git commit 信息等动态信息时非常有用。

      import platform
import sys
import os

def write_properties(temp_path):
    """
    生成 environment.properties 文件到指定的 Allure 结果目录。
    """
    os_name = platform.platform()
    python_version = sys.version
    try:
        AllureVersion = os.popen('allure --version').read().strip()
    except:
        AllureVersion = "N/A"  # 处理 allure 命令不可用的情况

    text = f"System={os_name}\nPythonVersion={python_version}\nAllureVersion={AllureVersion}\nauthor=yys"
    filepath = os.path.join(temp_path, 'environment.properties')

    with open(filepath, 'w', encoding='utf-8') as f:
        f.write(text)

    print(f"环境信息已写入: {filepath}")

# 示例用法（在 pytest.main 之后，allure generate 之前调用）：
# pytest.main(...)
# write_properties('./allure-results') # 确保与 --alluredir 的路径一致
# os.system("allure generate ./allure-results -o ./allure-report --clean")

    3. 防止 environment.properties 被删除：

      由于 --clean-alluredir 参数会清空 allure-results 目录，导致 environment.properties 文件被删除。 解决方法是在运行 Allure 报告生成命令之前，将 environment.properties 文件复制到 allure-results 目录。 (或者采用上面的动态生成方式。)

      import os
import shutil

# ... 其他代码 ...

pytest.main(['-vs', 'your_test_file.py', '--alluredir=./allure-results', '--clean-alluredir'])
# 写入 environment.properties (或者复制现有的文件)
write_properties('./allure-results')

# 或者复制现有的文件:
# shutil.copyfile('environment.properties', './allure-results/environment.properties')

os.system("allure generate ./allure-results -o ./allure-report --clean")

  • 步骤 (Steps)：

    使用 with allure.step() 将测试逻辑分解为更小的步骤，以便更好地理解测试流程。

    import allure

def test_example():
    with allure.step("步骤 1：初始化"):
        # 执行初始化操作
        pass

    with allure.step("步骤 2：执行主要操作"):
        # 执行测试的核心逻辑
        assert 1 == 1

    with allure.step("步骤 3：清理"):
        # 执行清理操作
        pass

    或者使用 @allure.step 装饰器：

    import allure

@allure.step("验证结果")
def verify_result(expected, actual):
    assert expected == actual

def test_with_decorated_step():
    expected_value = 10
    actual_value = 10
    verify_result(expected_value, actual_value)

  • Features 和 Stories：

    使用 @allure.feature 和 @allure.story 装饰器对测试用例进行分类和组织。

    import allure

@allure.feature("用户登录")
@allure.story("使用有效用户名和密码登录")
def test_login_with_valid_credentials():
    # 测试步骤
    pass

@allure.feature("用户登录")
@allure.story("使用无效用户名登录")
def test_login_with_invalid_username():
    # 测试步骤
    pass

  • Severity：

    使用 @allure.severity 装饰器指定测试用例的严重程度 (例如：blocker, critical, normal, minor, trivial)。

    import allure
from allure_commons.types import Severity

@allure.severity(Severity.CRITICAL)
def test_critical_functionality():
    # 测试步骤
    pass

  • 链接 (Links)：

    使用 @allure.link 装饰器添加链接到测试用例 (例如：Bug tracking 系统、需求文档)。

    import allure

@allure.link("https://example.com/issue/123", name="Bug Report")
def test_with_link():
    # 测试步骤
    pass

  • 参数化测试:

    Allure 能够很好地支持 pytest 的参数化测试。参数将会显示在报告中。

    import pytest
import allure

@allure.title("测试数据：{data}")  # 使用 title 可以在报告中显示参数
@pytest.mark.parametrize("data", [1, 2, 3])
def test_parameterized(data):
    with allure.step(f"使用数据 {data} 进行测试"):
        assert data > 0

  • 测试状态：

    Allure 报告中会显示测试用例的状态（Passed, Failed, Skipped, Broken, Unknown）。

    • Passed (通过): 测试用例成功通过。
    • Failed (失败): 测试用例断言失败。
    • Skipped (跳过): 测试用例被跳过 (例如，使用 @pytest.mark.skip)。
    • Broken (损坏): 测试用例执行过程中发生异常 (通常表示测试代码存在问题)。
    • Unknown (未知): 测试结果无法确定。

    示例 (与您提供的代码类似)：

    import pytest
import allure
from allure_commons.types import Severity

@allure.feature('测试状态')
@allure.story('通过')
def test_passed():
    with allure.step("Step 1: 执行一个简单的断言"):
        assert 1 == 1, "此断言应该为真"

@allure.feature('测试状态')
@allure.story('失败')
def test_failed():
    with allure.step("Step 1: 执行一个失败的断言"):
        assert 1 == 2, "此断言应该为假"

@allure.feature('测试状态')
@allure.story('跳过')
@pytest.mark.skip(reason="这个测试用例被跳过了")
def test_skipped():
    with allure.step("Step 1: 一个不会执行的步骤"):
        assert 1 == 1

@allure.feature('测试状态')
@allure.story('损坏')
def test_broken():
    with allure.step("Step 1: 引发一个意外异常"):
        raise Exception("这是一个意外异常")

4. 常见问题及解决方案

  • /usr/bin/env: node: 没有那个文件或目录 错误：

    • 原因： allure 命令依赖 Node.js，但系统找不到 node 可执行文件。
    • 解决方案：
      1. 确保 Node.js 已正确安装。
      2. 确认 node 命令在 PATH 环境变量中。 如果不在，将 Node.js 的安装目录添加到 PATH 变量中。 (通常是 /usr/local/bin 或 /usr/bin)
      3. 在Jenkins等构建工具中, 可以在构建步骤中加入 export PATH="/usr/local/bin:$PATH" 确保构建过程中能找到 node。

  • Windows CMD 乱码：

    • 原因： CMD 默认编码不是 UTF-8，导致 Allure 生成报告时中文显示乱码。

    • 解决方案：

      1. 在 CMD 中执行 chcp 65001 将编码设置为 UTF-8。
      2. 运行 allure generate allure-results -o allure-report --clean 生成报告。
      3. （可选）使用完毕后，运行 chcp 936 将编码恢复为默认的 GBK。

      更佳方案：

      • 修改 CMD 默认编码：
        1. 运行 regedit 打开注册表编辑器。
        2. 导航到 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Command Processor
        3. 新建字符串值 (String Value)，命名为 Autorun，值为 chcp 65001
        4. 重启 CMD 生效。 这样可以永久修改 CMD 默认编码。

  • Allure 报告中步骤没有显示，或者显示不正确：

    • 原因: allure 的步骤信息没有正确被pytest收集。
    • 解决方案: 确保 allure-pytest 已经正确安装并且启用了。检查 pytest.ini 文件中 --alluredir 参数是否正确设置。 确保测试函数使用了 with allure.step() 或者 @allure.step 装饰器。

  • Allure 报告中缺少环境信息：

    • 原因： 没有创建 environment.properties 文件，或者文件内容格式不正确，或者文件被 --clean-alluredir 参数删除。
    • 解决方案： 按照上述 "添加环境配置信息" 部分的步骤操作，确保正确创建和维护 environment.properties 文件，并防止其被删除。

  • Jenkins 集成问题:

    • 确保 Jenkins 服务器上已经安装了 JDK 和 Allure 命令行工具, 并且配置好了环境变量。
    • 在 Jenkins Job 配置中, 添加构建后操作 "Allure Report", 指定 Allure 结果目录 (即 --alluredir 参数指定的目录)。
    • 如果遇到权限问题, 确保 Jenkins 用户有权限访问 Allure 结果目录和报告输出目录。

5. 高级技巧

  • 自定义 Allure 报告：

    Allure 允许您自定义报告的外观和行为。 您可以创建自定义模板、添加自定义 CSS 样式等。 具体请参考 Allure 官方文档。

  • 与持续集成工具集成：

    Allure 可以与 Jenkins、TeamCity 等持续集成工具集成，以便自动生成和发布测试报告。 这些工具通常提供 Allure 插件，可以简化集成过程。

总结

allure-pytest 是一个强大的工具，可以帮助您创建美观、详细、易于理解的测试报告。 通过充分利用 Allure 的各种功能，您可以更好地组织和分析测试结果，提高测试效率和质量。 希望本文能够帮助您更好地使用 allure-pytest。