Allure Handle - 轻量级 Allure 报告工具

轻量级、零依赖的 Allure 报告增强工具包

一个专为 pytest + Allure 测试框架设计的工具包，提供便捷的 Allure 报告增强功能，让测试报告更加丰富和易读。

---

✨ 特性

• 🎯 轻量级：最小化依赖，只依赖 allure-pytest
• 🚀 简单易用：提供简洁的 API，快速集成到现有测试用例
• 📊 报告增强：支持测试数据、用例描述、步骤附件等丰富功能
• 🔧 自动检测：自动检测 Allure CLI 工具，无需手动配置
• 📦 独立包：可作为独立 pip 包安装和使用

---

📦 安装

方式1: 从 PyPI 安装（推荐）

pip install allurehandle-lit

方式2: 从 GitHub 安装

# 直接安装（推荐）
pip install git+https://github.com/Aquarius-0455/Allurehandle-Lit.git

# 或者指定分支/标签
pip install git+https://github.com/Aquarius-0455/Allurehandle-Lit.git@main

方式3: 从源码安装

# 克隆仓库
git clone https://github.com/Aquarius-0455/Allurehandle-Lit.git
cd Allurehandle-Lit

# 安装
pip install -e .

---

🚀 快速开始

1. 安装依赖

pip install allurehandle-lit pytest allure-pytest

2. 查看 Demo 示例

项目包含完整的演示文件 demo_allure.py，展示了所有功能的使用方法：

# 查看演示代码
cat demo_allure.py

# 或直接运行演示
python demo_allure.py

3. 运行测试并生成报告

# 运行测试
pytest --alluredir=reports/allure_results

# 生成并打开 Allure 报告
allure generate reports/allure_results -o reports/allure_reports --clean
allure open reports/allure_reports

---

📖 API 文档

AllureHandle.add_testdata_to_report(testdata, title="测试数据")

将测试数据添加到 Allure 报告中。

参数：

• testdata (dict): 测试数据字典
• title (str): 数据标题，默认为 "测试数据"

示例（来自 demo_allure.py）：

testdata = {
    "username": "test_user_001",
    "email": "test@example.com",
    "phone": "13800138000",
    "age": 25
}
AllureHandle.add_testdata_to_report(testdata, "创建用户测试数据")

---

AllureHandle.add_case_description_html(case_data)

添加格式化的用例描述到 Allure 报告中。

参数：

• case_data (dict): 用例数据字典，包含以下字段：
  • case_id (str): 用例ID
  • case_module (str): 用例模块
  • case_name (str): 用例名称
  • case_priority (int): 优先级（1-低, 2-中, 3-高）
  • case_setup (str): 前置条件
  • case_step (str): 测试步骤
  • case_expect_result (str): 预期结果
  • case_result (str): 测试结果（passed/failed/skipped）

示例（来自 demo_allure.py）：

case_data = {
    'case_id': 'TC_USER_001',
    'case_module': '用户管理',
    'case_name': '创建新用户',
    'case_priority': 3,  # 1-低, 2-中, 3-高
    'case_setup': '系统已登录，具备用户管理权限',
    'case_step': '''1. 准备用户测试数据
2. 调用创建用户接口
3. 验证返回结果
4. 检查用户是否创建成功''',
    'case_expect_result': '用户创建成功，返回用户ID和基本信息',
    'case_result': 'passed'
}
AllureHandle.add_case_description_html(case_data)

---

AllureHandle.add_step_with_attachment(title, content, attachment_type="TEXT")

添加步骤附件到 Allure 报告中。

参数：

• title (str): 附件标题
• content (str): 附件内容
• attachment_type (str): 附件类型，可选值：
  • "TEXT": 文本
  • "JSON": JSON 格式
  • "HTML": HTML 格式
  • "XML": XML 格式

示例（来自 demo_allure.py）：

# 添加 JSON 格式附件
response = {
    "code": 200,
    "message": "success",
    "data": {
        "user_id": "12345",
        "username": "test_user_001",
        "created_at": "2024-01-01 10:00:00"
    }
}
AllureHandle.add_step_with_attachment(
    title="接口响应",
    content=str(response),
    attachment_type="JSON"
)

# 添加 TEXT 格式附件
AllureHandle.add_step_with_attachment(
    title="更新响应",
    content="更新成功",
    attachment_type="TEXT"
)

---

AllureHandle.generate_report(results_dir, report_dir, clean=True)

生成 Allure 报告。

参数：

• results_dir (str): Allure 结果目录，默认为 "reports/allure_results"
• report_dir (str): 报告输出目录，默认为 "reports/allure_reports"
• clean (bool): 是否清理旧报告，默认为 True

示例（来自 demo_allure.py）：

# 自动生成报告（demo_allure.py 中已实现）
def generate_allure_report():
    RESULTS_DIR.mkdir(parents=True, exist_ok=True)
    REPORT_DIR.mkdir(parents=True, exist_ok=True)
    
    if not check_allure_installed():
        print("Allure CLI 未安装，无法生成报告")
        return False
    
    cmd = [
        "allure", "generate",
        str(RESULTS_DIR),
        "-o", str(REPORT_DIR),
        "--clean"
    ]
    result = subprocess.run(cmd, capture_output=True, text=True, shell=True)
    return result.returncode == 0

# 或使用 AllureHandle 方法
AllureHandle.generate_report(
    results_dir="reports/allure_results",
    report_dir="reports/allure_reports",
    clean=True
)

---

📁 项目结构

Allurehandle-Lit/
├── allure_handle/          # 核心包
│   ├── __init__.py
│   ├── allure_handle.py   # 主模块
│   ├── example.py          # 使用示例
│   └── README.md           # 包说明文档
├── demo_allure.py          # 完整演示文件（推荐）
├── README_DEMO.md          # Demo 使用说明
├── setup.py                # 安装配置
├── pyproject.toml          # 项目配置
├── MANIFEST.in             # 打包清单
├── requirements.txt         # 依赖列表
├── README.md               # 项目说明（本文件）
└── PACKAGE_INSTALL.md      # 打包安装指南

---

🔧 配置

Allure CLI 工具检测

AllureHandle 会自动检测系统中是否安装了 Allure CLI 工具：

1. 首先检查环境变量 ALLURE_HOME
2. 然后检查系统 PATH
3. 如果未找到，会提示安装方法

手动设置 Allure 路径：

import os
os.environ['ALLURE_HOME'] = '/path/to/allure'

---

📝 完整示例

查看 allure_handle/example.py 获取完整的使用示例。

---

🎯 运行 Demo 演示

项目包含一个完整的演示文件 demo_allure.py，可以直接运行查看效果。

快速开始

# 1. 克隆仓库
git clone https://github.com/Aquarius-0455/Allurehandle-Lit.git
cd Allurehandle-Lit

# 2. 安装依赖
pip install allurehandle-lit pytest allure-pytest

# 3. 运行 Demo（会自动生成报告）
python demo_allure.py

Demo 功能

demo_allure.py 演示了以下功能：

• ✅ 测试数据展示 - 在报告中以表格形式展示测试数据
• ✅ 用例描述 - 格式化的 HTML 用例描述，包含用例ID、优先级等信息
• ✅ 步骤附件 - 支持 JSON、TEXT、HTML 等格式的附件
• ✅ 测试分类 - 使用 Epic、Feature、Story、Severity 进行分类
• ✅ 自动生成报告 - 运行后自动生成并打开 Allure 报告

手动生成报告

如果自动生成失败，可以手动生成：

# 运行测试生成结果
pytest demo_allure.py --alluredir=reports/allure_results -v

# 生成报告（需要先安装 Allure CLI）
allure generate reports/allure_results -o reports/allure_reports --clean

# 打开报告
allure open reports/allure_reports

安装 Allure CLI

如果还没有安装 Allure CLI，可以：

Windows:

# 使用 Scoop
scoop install allure

# 或使用 Chocolatey
choco install allure-commandline

Mac:

brew install allure

Linux:

# Ubuntu/Debian
sudo apt-add-repository ppa:qameta/allure
sudo apt-get update
sudo apt-get install allure

更多安装方法请查看 Allure 官方文档。

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

📄 许可证

MIT License

---

🔗 相关链接

• Allure 官方文档
• pytest 官方文档
• allure-pytest 文档

---

作者： Lit
最后更新： 2024-12-31