feat: 建立Allure测试报告系统

- 安装allure-playwright和allure-commandline依赖 - 添加Allure相关的npm脚本（test:allure、test:allure:open、test:allure:serve） - 在playwright.config.ts中集成Allure reporter - 创建Allure测试报告系统使用指南 - 支持测试描述、步骤、标签、严重级别、套件、链接、附件、参数等功能 - 支持CI/CD集成（Woodpecker、GitHub Actions、GitLab CI）
2026-02-28 16:46:55 +08:00
parent 927264b2f0
commit eeccc59630
3 changed files with 688 additions and 2 deletions
@@ -0,0 +1,674 @@
+# 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  
+**维护者**: 张翔
@@ -12,14 +12,21 @@
    "test:performance": "playwright test --grep @performance",
    "test:responsive": "playwright test --grep @responsive",
    "test:visual": "playwright test --grep @visual",
+    "test:accessibility": "playwright test --grep @accessibility",
+    "test:security": "playwright test --grep @security",
    "test:report": "playwright show-report",
+    "test:allure": "allure generate allure-results --clean -o allure-report",
+    "test:allure:open": "allure open allure-report",
+    "test:allure:serve": "allure serve allure-results",
    "test:all-with-progress": "node run-tests-with-progress.js",
    "install": "playwright install --with-deps"
  },
  "devDependencies": {
    "@axe-core/playwright": "^4.9.0",
-    "@playwright/test": "^1.48.0",
+    "@playwright/test": "^1.58.2",
    "@types/node": "^20.11.0",
+    "allure-commandline": "^2.37.0",
+    "allure-playwright": "^3.5.0",
    "glob": "^13.0.6",
    "typescript": "^5.3.0"
  }
@@ -14,7 +14,12 @@ export default defineConfig({
    ['json', { outputFile: 'test-results/results.json' }],
    ['junit', { outputFile: 'test-results/junit.xml' }],
    ['line'],
-    ['list']
+    ['list'],
+    ['allure-playwright', {
+      outputFolder: 'allure-results',
+      detail: true,
+      suiteTitle: false,
+    }],
  ],
  timeout: env.timeout,
  expect: {