novalon-website/e2e/docs/allure-report-guide.md

Allure测试报告系统使用指南

概述

Allure是一个灵活的、轻量级的多语言测试报告工具，能够生成美观、详细的测试报告。本文档介绍如何在E2E测试项目中集成和使用Allure报告系统。

---

一、安装和配置

1.1 安装依赖

cd e2e
npm install --save-dev @playwright/test allure-playwright allure-commandline

1.2 配置Playwright

在playwright.config.ts中添加Allure reporter：

export default defineConfig({
  reporter: [
    ['html', { open: 'never' }],
    ['json', { outputFile: 'test-results/results.json' }],
    ['junit', { outputFile: 'test-results/junit.xml' }],
    ['line'],
    ['list'],
    ['allure-playwright', {
      outputFolder: 'allure-results',
      detail: true,
      suiteTitle: false,
    }],
  ],
});

1.3 添加npm脚本

在package.json中添加Allure相关脚本：

{
  "scripts": {
    "test": "playwright test",
    "test:allure": "allure generate allure-results --clean -o allure-report",
    "test:allure:open": "allure open allure-report",
    "test:allure:serve": "allure serve allure-results"
  }
}

---

二、基本使用

2.1 运行测试并生成报告

# 1. 运行测试
npm run test

# 2. 生成Allure报告
npm run test:allure

# 3. 打开报告
npm run test:allure:open

2.2 实时查看报告

# 在测试运行时实时查看报告
npm run test:allure:serve

2.3 清理历史报告

# 清理旧的报告数据
rm -rf allure-results allure-report

---

三、Allure注解

3.1 测试描述

使用@allure.description添加测试描述：

import { test } from '@playwright/test';
import { allure } from 'allure-playwright';

test('测试用例描述', async ({ page }) => {
  allure.description('这是一个测试用例的详细描述');
  // 测试逻辑
});

3.2 测试步骤

使用allure.step添加测试步骤：

import { test } from '@playwright/test';
import { allure } from 'allure-playwright';

test('测试步骤示例', async ({ page }) => {
  await allure.step('步骤1: 打开首页', async () => {
    await page.goto('/');
  });

  await allure.step('步骤2: 点击导航链接', async () => {
    await page.click('nav a');
  });

  await allure.step('步骤3: 验证页面加载', async () => {
    await expect(page).toHaveURL('/about');
  });
});

3.3 测试标签

使用@allure.tag添加测试标签：

import { test } from '@playwright/test';
import { allure } from 'allure-playwright';

test('测试标签示例', async ({ page }) => {
  allure.tags('smoke', 'regression', 'high-priority');
  // 测试逻辑
});

3.4 测试严重级别

使用@allure.severity添加测试严重级别：

import { test } from '@playwright/test';
import { allure } from 'allure-playwright';

test('测试严重级别示例', async ({ page }) => {
  allure.severity('critical');
  // 测试逻辑
});

支持的严重级别：

• blocker: 阻塞级别
• critical: 严重级别
• normal: 普通级别
• minor: 次要级别
• trivial: 微不足道级别

3.5 测试套件

使用@allure.suite添加测试套件：

import { test } from '@playwright/test';
import { allure } from 'allure-playwright';

test.describe('测试套件示例', () => {
  test.beforeEach(async () => {
    allure.suite('首页测试');
  });

  test('测试用例1', async ({ page }) => {
    // 测试逻辑
  });

  test('测试用例2', async ({ page }) => {
    // 测试逻辑
  });
});

3.6 测试链接

使用@allure.link添加测试链接：

import { test } from '@playwright/test';
import { allure } from 'allure-playwright';

test('测试链接示例', async ({ page }) => {
  allure.link('https://example.com/ticket/123', 'JIRA链接');
  allure.issue('123', 'JIRA问题');
  allure.tms('456', '测试用例管理');
  // 测试逻辑
});

3.7 附件

使用allure.attachment添加附件：

import { test } from '@playwright/test';
import { allure } from 'allure-playwright';

test('附件示例', async ({ page }) => {
  await page.goto('/');
  
  // 添加截图附件
  const screenshot = await page.screenshot();
  allure.attachment('首页截图', screenshot, 'image/png');
  
  // 添加文本附件
  allure.attachment('页面URL', page.url(), 'text/plain');
  
  // 添加JSON附件
  const data = { key: 'value' };
  allure.attachment('测试数据', JSON.stringify(data), 'application/json');
});

3.8 测试参数

使用@allure.parameter添加测试参数：

import { test } from '@playwright/test';
import { allure } from 'allure-playwright';

test('测试参数示例', async ({ page }) => {
  const browser = 'chromium';
  const viewport = { width: 1280, height: 720 };
  
  allure.parameter('浏览器', browser);
  allure.parameter('视口大小', `${viewport.width}x${viewport.height}`);
  
  // 测试逻辑
});

---

四、高级功能

4.1 环境信息

创建allure-results/environment.properties文件：

# Environment Properties
Browser=Chromium
Browser.Version=120.0.0
OS=macOS
OS.Version=14.0
Environment=staging
BaseURL=https://staging.novalon.com

4.2 测试分类

创建allure-results/categories.json文件：

[
  {
    "name": "Ignored tests",
    "matchedStatuses": ["skipped"]
  },
  {
    "name": "Infrastructure problems",
    "matchedStatuses": ["broken", "failed"],
    "messageRegex": ".*Connection refused.*"
  },
  {
    "name": "Outdated tests",
    "matchedStatuses": ["broken"],
    "traceRegex": ".*FileNotFoundException.*"
  },
  {
    "name": "Product defects",
    "matchedStatuses": ["failed"]
  },
  {
    "name": "Test defects",
    "matchedStatuses": ["broken"]
  }
]

4.3 自定义测试执行器

创建allure-results/executor.json文件：

{
  "name": "Woodpecker CI",
  "type": "woodpecker",
  "url": "https://ci.example.com",
  "buildOrder": "123",
  "buildName": "E2E Tests #123",
  "buildUrl": "https://ci.example.com/build/123",
  "reportUrl": "https://ci.example.com/build/123/allure",
  "reportName": "Allure Report"
}

---

五、CI/CD集成

5.1 Woodpecker CI集成

# .woodpecker.yml
steps:
  - name: Run Tests
    image: mcr.microsoft.com/playwright:v1.48.0
    commands:
      - cd e2e
      - npm ci
      - npm run test
    environment:
      ALLURE_RESULTS_PATH: allure-results

  - name: Generate Allure Report
    image: frankescobar/allure-docker-service
    commands:
      - cd e2e
      - allure generate allure-results --clean -o allure-report
    when:
      status: [success, failure]

  - name: Upload Allure Report
    image: plugins/s3
    settings:
      bucket: test-reports
      source: e2e/allure-report/**
      target: /allure/${CI_COMMIT_SHA}
    when:
      status: [success, failure]

5.2 GitHub Actions集成

# .github/workflows/e2e-tests.yml
name: E2E Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: |
          cd e2e
          npm ci
          
      - name: Run tests
        run: |
          cd e2e
          npm run test
          
      - name: Generate Allure Report
        run: |
          cd e2e
          npm run test:allure
          
      - name: Upload Allure Report
        uses: actions/upload-artifact@v3
        with:
          name: allure-report
          path: e2e/allure-report

5.3 GitLab CI集成

# .gitlab-ci.yml
stages:
  - test
  - report

test:
  stage: test
  image: mcr.microsoft.com/playwright:v1.48.0
  script:
    - cd e2e
    - npm ci
    - npm run test
  artifacts:
    when: always
    paths:
      - e2e/allure-results/
    expire_in: 1 week

report:
  stage: report
  image: frankescobar/allure-docker-service
  script:
    - cd e2e
    - allure generate allure-results --clean -o allure-report
    - allure open allure-report
  artifacts:
    when: always
    paths:
      - e2e/allure-report/
    expire_in: 1 week
  dependencies:
    - test

---

六、报告分析

6.1 测试概览

Allure报告提供以下概览信息：

• 测试总数
• 通过/失败/跳过的测试数量
• 测试执行时间
• 测试通过率
• 测试趋势

6.2 测试套件

按测试套件查看测试结果：

• 每个套件的测试数量
• 每个套件的通过率
• 每个套件的执行时间

6.3 测试用例

查看每个测试用例的详细信息：

• 测试描述
• 测试步骤
• 测试参数
• 测试附件
• 测试日志
• 测试截图

6.4 测试趋势

查看测试趋势图表：

• 测试通过率趋势
• 测试执行时间趋势
• 测试数量趋势

6.5 测试分类

按分类查看测试结果：

• Ignored tests（被忽略的测试）
• Infrastructure problems（基础设施问题）
• Outdated tests（过时的测试）
• Product defects（产品缺陷）
• Test defects（测试缺陷）

---

七、最佳实践

7.1 使用描述性测试名称

// ✅ 好的做法
test('应该能够成功提交联系表单', async ({ page }) => {
  // 测试逻辑
});

// ❌ 不好的做法
test('测试1', async ({ page }) => {
  // 测试逻辑
});

7.2 添加详细的测试步骤

// ✅ 好的做法
test('完整的测试步骤', async ({ page }) => {
  await allure.step('步骤1: 打开首页', async () => {
    await page.goto('/');
    await page.waitForLoadState('networkidle');
  });

  await allure.step('步骤2: 填写联系表单', async () => {
    await page.fill('input[name="name"]', '张三');
    await page.fill('input[name="email"]', 'zhangsan@example.com');
    await page.fill('input[name="phone"]', '13800138000');
    await page.fill('textarea[name="message"]', '测试消息');
  });

  await allure.step('步骤3: 提交表单', async () => {
    await page.click('button[type="submit"]');
    await page.waitForSelector('.success');
  });
});

// ❌ 不好的做法
test('没有测试步骤', async ({ page }) => {
  await page.goto('/');
  await page.fill('input[name="name"]', '张三');
  await page.fill('input[name="email"]', 'zhangsan@example.com');
  await page.fill('input[name="phone"]', '13800138000');
  await page.fill('textarea[name="message"]', '测试消息');
  await page.click('button[type="submit"]');
  await page.waitForSelector('.success');
});

7.3 使用测试标签

// ✅ 好的做法
test('带标签的测试', async ({ page }) => {
  allure.tags('smoke', 'regression', 'high-priority');
  allure.severity('critical');
  // 测试逻辑
});

// ❌ 不好的做法
test('没有标签的测试', async ({ page }) => {
  // 测试逻辑
});

7.4 添加测试附件

// ✅ 好的做法
test('带附件的测试', async ({ page }) => {
  await page.goto('/');
  
  const screenshot = await page.screenshot();
  allure.attachment('首页截图', screenshot, 'image/png');
  
  const pageContent = await page.content();
  allure.attachment('页面HTML', pageContent, 'text/html');
  
  // 测试逻辑
});

// ❌ 不好的做法
test('没有附件的测试', async ({ page }) => {
  await page.goto('/');
  // 测试逻辑
});

7.5 使用测试参数

// ✅ 好的做法
test('带参数的测试', async ({ page }) => {
  const testData = {
    name: '张三',
    email: 'zhangsan@example.com',
    phone: '13800138000',
  };
  
  allure.parameter('测试数据', JSON.stringify(testData));
  allure.parameter('浏览器', 'chromium');
  
  // 测试逻辑
});

// ❌ 不好的做法
test('没有参数的测试', async ({ page }) => {
  // 测试逻辑
});

---

八、故障排查

8.1 报告生成失败

问题: 运行npm run test:allure时报告生成失败。

原因: allure-results目录不存在或为空。

解决方案:

# 确保先运行测试
npm run test

# 检查allure-results目录
ls -la allure-results

# 如果目录为空，重新运行测试
rm -rf allure-results
npm run test

8.2 报告打开失败

问题: 运行npm run test:allure:open时报告无法打开。

原因: allure-report目录不存在或Allure未正确安装。

解决方案:

# 重新生成报告
npm run test:allure

# 检查allure-report目录
ls -la allure-report

# 重新安装Allure
npm install --save-dev allure-commandline

8.3 测试步骤不显示

问题: Allure报告中没有显示测试步骤。

原因: 没有使用allure.step添加测试步骤。

解决方案:

// 添加测试步骤
await allure.step('步骤描述', async () => {
  // 测试逻辑
});

8.4 附件不显示

问题: Allure报告中没有显示附件。

原因: 没有使用allure.attachment添加附件或附件路径不正确。

解决方案:

// 添加附件
const screenshot = await page.screenshot();
allure.attachment('截图', screenshot, 'image/png');

---

九、总结

Allure测试报告系统提供了强大的测试报告功能，包括：

1. 美观的报告界面: 直观的UI设计，易于理解
2. 详细的测试信息: 测试描述、步骤、参数、附件等
3. 测试趋势分析: 通过率、执行时间、测试数量趋势
4. 测试分类: 按缺陷类型分类，便于问题定位
5. CI/CD集成: 支持多种CI/CD工具集成

通过使用Allure报告系统，可以更好地了解测试执行情况，快速定位问题，提高测试效率。

---

文档版本: v1.0
最后更新: 2026-02-28
维护者: 张翔