everything-is-suitable/docs/usage-examples.md

# 自动化测试框架使用示例

本文档提供详细的自动化测试框架使用示例，帮助您快速上手。

---

## 📋 目录

1. [环境准备](#环境准备)
2. [智能测试选择器](#智能测试选择器)
3. [测试执行](#测试执行)
4. [测试报告](#测试报告)
5. [CI/CD集成](#cicd集成)
6. [常见场景](#常见场景)

---

## 环境准备

### 1. 验证环境配置

在开始之前，请先验证环境配置是否正确：

```bash
# 验证环境变量
./scripts/verify-env.sh

# 初始化测试数据库
./scripts/init-test-database.sh

# 初始化测试数据（可选）
npm run ts-node scripts/init-test-data.ts
```

### 2. 启动测试环境

```bash
# 启动容器化测试环境
docker-compose -f docker-compose.test.yml up -d

# 查看容器状态
docker-compose -f docker-compose.test.yml ps

# 查看容器日志
docker-compose -f docker-compose.test.yml logs -f
```

### 3. 停止测试环境

```bash
# 停止测试环境
docker-compose -f docker-compose.test.yml down

# 停止并清理数据
docker-compose -f docker-compose.test.yml down -v
```

---

## 智能测试选择器

### 基本用法

#### 1. 从文件读取变更列表

```bash
# 创建变更文件列表
echo "everything-is-suitable-admin/src/views/UserManagement.vue" > changed-files.txt
echo "everything-is-suitable-admin/src/api/user.ts" >> changed-files.txt

# 运行智能测试选择器
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --output selected-tests.json \
  --report test-selection-report.md
```

#### 2. 使用Git获取变更文件

```bash
# 获取相对于main分支的变更
git diff --name-only origin/main...HEAD > changed-files.txt

# 运行智能测试选择器
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --output selected-tests.json \
  --report test-selection-report.md
```

### 高级用法

#### 1. 按优先级过滤

```bash
# 只选择高优先级测试
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --priority high \
  --output selected-tests.json

# 选择高优先级和中等优先级测试
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --priority medium \
  --output selected-tests.json
```

#### 2. 按测试级别过滤

```bash
# 只选择冒烟测试
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --level smoke \
  --output selected-tests.json

# 选择冒烟测试和功能测试
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --level functional \
  --output selected-tests.json
```

#### 3. 禁用关联分析

```bash
# 只选择直接相关的测试，不包括关联模块的测试
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --no-include-related \
  --output selected-tests.json
```

### 查看选择结果

```bash
# 查看JSON格式的选择结果
cat selected-tests.json | jq .

# 查看Markdown格式的分析报告
cat test-selection-report.md
```

---

## 测试执行

### 智能测试执行

#### 1. 执行智能选择的测试

```bash
# 使用之前生成的选择结果
npm run test:smart selected-tests.json

# 或者直接使用编译后的脚本
node dist/scripts/run-selected-tests.js selected-tests.json
```

#### 2. 执行全量测试

```bash
# 执行所有测试
npm run test:all

# 或者使用Playwright直接执行
npx playwright test
```

### 按测试级别执行

#### 1. 执行冒烟测试

```bash
# 只执行标记为@smoke的测试
npx playwright test --grep @smoke
```

#### 2. 执行功能测试

```bash
# 执行标记为@functional的测试
npx playwright test --grep @functional
```

#### 3. 执行边缘场景测试

```bash
# 执行标记为@edge的测试
npx playwright test --grep @edge
```

### 按模块执行

```bash
# 执行用户管理模块的测试
npx playwright test e2e/user-management/

# 执行角色管理模块的测试
npx playwright test e2e/role-management/

# 执行API测试
npx playwright test e2e/api/
```

### 调试模式

```bash
# 以UI模式运行测试
npx playwright test --ui

# 以调试模式运行测试
npx playwright test --debug

# 以 headed 模式运行测试（显示浏览器）
npx playwright test --headed

# 慢速运行（每个操作延迟1000ms）
npx playwright test --slow-mo=1000
```

---

## 测试报告

### 生成测试报告

#### 1. 生成HTML报告

```bash
# 执行测试并生成HTML报告
npx playwright test --reporter=html

# 打开HTML报告
npx playwright show-report
```

#### 2. 生成JSON报告

```bash
# 执行测试并生成JSON报告
npx playwright test --reporter=json --output=test-results.json
```

#### 3. 生成JUnit报告

```bash
# 执行测试并生成JUnit报告
npx playwright test --reporter=junit --output=junit-results.xml
```

### 生成覆盖率报告

```bash
# 执行测试并生成覆盖率报告
npm run test:coverage

# 查看覆盖率报告
open coverage/index.html
```

### 生成趋势报告

```bash
# 生成测试趋势报告
npm run test:report

# 查看趋势报告
open test-trend-report.html
```

---

## CI/CD集成

### Woodpecker CI

#### 1. 自动触发

当有代码推送到仓库时，Woodpecker CI会自动执行以下步骤：

1. **智能测试选择**：分析代码变更，选择相关测试
2. **智能测试执行**：执行选择的测试用例
3. **测试报告生成**：生成测试报告并上传

#### 2. 手动触发

```bash
# 在Woodpecker CI界面手动触发构建
# 或者使用CLI工具
woodpecker-cli build start <repo> <build>
```

#### 3. 定时触发

```yaml
# .woodpecker.yml
when:
  - event: cron
    cron: daily-test
```

### GitHub Actions（示例）

```yaml
name: Smart Test

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

jobs:
  smart-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: npm ci
      
      - name: Get changed files
        run: |
          git diff --name-only origin/main...HEAD > changed-files.txt || echo "[]" > changed-files.txt
      
      - name: Smart test selection
        run: |
          node dist/scripts/scripts/cli/smart-test-selector-cli.js \
            --input changed-files.txt \
            --output selected-tests.json \
            --report test-selection-report.md
      
      - name: Run smart tests
        run: npm run test:smart selected-tests.json
      
      - name: Upload test results
        uses: actions/upload-artifact@v3
        with:
          name: test-results
          path: |
            selected-tests.json
            test-selection-report.md
```

---

## 常见场景

### 场景1：开发新功能

```bash
# 1. 创建新分支
git checkout -b feature/user-profile

# 2. 开发新功能
# ... 编写代码 ...

# 3. 验证环境配置
./scripts/verify-env.sh

# 4. 获取变更文件
git diff --name-only origin/main...HEAD > changed-files.txt

# 5. 智能选择测试
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --output selected-tests.json \
  --report test-selection-report.md

# 6. 执行测试
npm run test:smart selected-tests.json

# 7. 查看测试报告
npx playwright show-report

# 8. 提交代码
git add .
git commit -m "feat: add user profile feature"
git push origin feature/user-profile
```

### 场景2：修复Bug

```bash
# 1. 创建修复分支
git checkout -b fix/login-bug

# 2. 修复Bug
# ... 修改代码 ...

# 3. 只执行冒烟测试验证修复
git diff --name-only origin/main...HEAD > changed-files.txt
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --level smoke \
  --output selected-tests.json

npm run test:smart selected-tests.json

# 4. 提交修复
git add .
git commit -m "fix: resolve login issue"
git push origin fix/login-bug
```

### 场景3：重构代码

```bash
# 1. 创建重构分支
git checkout -b refactor/user-service

# 2. 重构代码
# ... 重构代码 ...

# 3. 执行全量测试确保重构没有破坏功能
npm run test:all

# 4. 查看覆盖率报告
npm run test:coverage
open coverage/index.html

# 5. 提交重构
git add .
git commit -m "refactor: improve user service structure"
git push origin refactor/user-service
```

### 场景4：发布前验证

```bash
# 1. 切换到发布分支
git checkout release/v1.0.0

# 2. 验证环境配置
./scripts/verify-env.sh

# 3. 执行全量测试
npm run test:all

# 4. 生成覆盖率报告
npm run test:coverage

# 5. 生成趋势报告
npm run test:report

# 6. 查看所有报告
open coverage/index.html
open test-trend-report.html
npx playwright show-report
```

### 场景5：本地调试测试

```bash
# 1. 以UI模式运行测试
npx playwright test --ui

# 2. 以调试模式运行特定测试
npx playwright test e2e/user-management/login.spec.ts --debug

# 3. 以 headed 模式运行测试
npx playwright test --headed --slow-mo=1000

# 4. 只运行失败的测试
npx playwright test --last-failed
```

---

## 📚 相关文档

- [故障排查指南](./troubleshooting-guide.md)
- [测试用例设计规范](./test-case-design-guide.md)
- [API文档](./api-documentation.md)
- [配置说明](./configuration-guide.md)

---

## 💡 最佳实践

1. **提交前验证**：每次提交代码前，先运行智能测试选择器验证变更
2. **优先级管理**：为测试用例设置合适的优先级，确保关键路径优先测试
3. **定期全量测试**：定期执行全量测试，确保系统整体质量
4. **覆盖率监控**：持续监控测试覆盖率，确保覆盖率不低于80%
5. **报告分析**：定期分析测试报告，识别不稳定的测试用例

---

## 🆘 获取帮助

如果遇到问题，请参考：

1. [故障排查指南](./troubleshooting-guide.md)
2. [项目文档](../README.md)
3. 联系测试团队

---

**文档版本**: v1.0  
**最后更新**: 2026-03-28  
**维护人员**: 张翔