# Allure测试报告系统使用指南

## 概述

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

---

## 一、安装和配置

### 1.1 安装依赖

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

### 1.2 配置Playwright

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

```typescript
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相关脚本：

```json
{
  "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 运行测试并生成报告

```bash
# 1. 运行测试
npm run test

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

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

### 2.2 实时查看报告

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

### 2.3 清理历史报告

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

---

## 三、Allure注解

### 3.1 测试描述

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

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

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

### 3.2 测试步骤

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

```typescript
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`添加测试标签：

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

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

### 3.4 测试严重级别

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

```typescript
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`添加测试套件：

```typescript
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`添加测试链接：

```typescript
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`添加附件：

```typescript
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`添加测试参数：

```typescript
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`文件：

```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`文件：

```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`文件：

```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集成

```yaml
# .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集成

```yaml
# .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集成

```yaml
# .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 使用描述性测试名称

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

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

### 7.2 添加详细的测试步骤

```typescript
// ✅ 好的做法
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 使用测试标签

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

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

### 7.4 添加测试附件

```typescript
// ✅ 好的做法
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 使用测试参数

```typescript
// ✅ 好的做法
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`目录不存在或为空。

**解决方案**:
```bash
# 确保先运行测试
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未正确安装。

**解决方案**:
```bash
# 重新生成报告
npm run test:allure

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

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

### 8.3 测试步骤不显示

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

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

**解决方案**:
```typescript
// 添加测试步骤
await allure.step('步骤描述', async () => {
  // 测试逻辑
});
```

### 8.4 附件不显示

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

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

**解决方案**:
```typescript
// 添加附件
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  
**维护者**: 张翔