# AI驱动测试自动化工具链

> **版本**: v1.0.0  
> **最后更新**: 2026-01-09

---

## 📋 目录

- [概述](#概述)
- [工具清单](#工具清单)
- [快速开始](#快速开始)
- [工具详解](#工具详解)
- [配置说明](#配置说明)
- [使用示例](#使用示例)
- [故障排查](#故障排查)

---

## 概述

本工具链实现了**AI驱动的测试自动化闭环**，包括：

1. **测试执行**：基于文档驱动的E2E测试执行
2. **报告生成**：结构化测试报告
3. **AI分析**：智能问题分类和根因分析
4. **自动修复**：Level 1-3分级修复策略
5. **智能回归**：根据修复范围动态选择回归策略
6. **文档同步**：代码与文档一致性检查

**核心优势**：
- ✅ **80%问题AI自动修复**（Level 1）
- ✅ **15%问题AI辅助修复**（Level 2）
- ✅ **5%问题人工处理**（Level 3）
- ✅ **文档驱动，无需编写测试代码**
- ✅ **智能回归，节省测试时间**

---

## 工具清单

| 工具 | 文件 | 职责 | 状态 |
|------|------|------|------|
| **Test Executor** | `test-executor.ts` | 封装Playwright MCP调用，执行测试 | ✅ |
| **Report Generator** | `report-generator.ts` | 生成结构化测试报告 | ✅ |
| **AI Analyzer** | `ai-analyzer.ts` | 问题分类和根因分析 | ✅ |
| **Auto Fixer** | `auto-fixer.ts` | Level 1-3分级修复 | ✅ |
| **Regression Scheduler** | `regression-scheduler.ts` | 智能回归测试调度 | ✅ |
| **Doc Sync Checker** | `doc-sync-checker.ts` | 文档一致性检查 | ✅ |

**辅助文件**：
- `types.ts` - TypeScript类型定义
- `mcp-client.ts` - Playwright MCP客户端封装

---

## 快速开始

### 1. 安装依赖

```bash
cd testing
npm install
```

### 2. 配置环境

```bash
# 复制配置模板
cp config/test-automation.config.ts.example config/test-automation.config.ts

# 设置环境变量
export TEST_ADMIN_PASSWORD="your_password"
export TEST_MANAGER_PASSWORD="your_password"
export TEST_EMPLOYEE_PASSWORD="your_password"
```

### 3. 执行测试

```bash
# 方式1：使用便捷脚本
npm run test:ai-driven -- --module organization

# 方式2：直接调用
npx ts-node tools/test-executor.ts --module organization
```

### 4. 查看报告

```bash
# 报告位置
ls test/organization-{timestamp}-e2e/

# 打开Markdown报告
open test/organization-{timestamp}-e2e/organization-{timestamp}-report.md
```

---

## 工具详解

### 1. Test Executor（测试执行器）

**职责**：
- 解析测试文档（`10-e2e-test-spec.md`）
- 调用Playwright MCP执行测试
- 收集执行结果和资产（截图、视频、trace）

**使用方式**：

```typescript
import { executeTest } from './tools/test-executor';

const results = await executeTest('organization', {
  environment: 'test',
  browser: 'chromium',
  headless: true,
});
```

**输出**：
- `TestResult[]` - 测试结果数组
- 资产文件（截图、视频、trace）

---

### 2. Report Generator（报告生成器）

**职责**：
- 将测试结果转换为结构化报告
- 生成Markdown和JSON格式
- 计算统计指标和覆盖率

**使用方式**：

```typescript
import { generateReport } from './tools/report-generator';

const report = await generateReport(context, results, aiAnalyses);
```

**输出**：
- Markdown报告：`{module}-{timestamp}-report.md`
- JSON数据：`{module}-{timestamp}-raw.json`

---

### 3. AI Analyzer（AI分析器）

**职责**：
- 分析测试失败原因
- 分类问题类型（10种）
- 判断修复Level（1-3）
- 生成修复建议

**使用方式**：

```typescript
import { analyzeFailure } from './tools/ai-analyzer';

const analysis = await analyzeFailure(failedResult);
console.log(`问题类型: ${analysis.problemCategory}`);
console.log(`修复Level: ${analysis.fixLevel}`);
```

**问题分类**：
1. `missing_data_testid` - 缺少data-testid
2. `selector_changed` - 选择器变更
3. `outdated_doc_content` - 文档内容过时
4. `api_change` - API变更
5. `business_logic_change` - 业务逻辑变更
6. `performance_issue` - 性能问题
7. `security_issue` - 安全问题
8. `architecture_issue` - 架构问题
9. `unknown` - 未知问题

---

### 4. Auto Fixer（自动修复器）

**职责**：
- 路由修复请求到Level 1-3
- 执行Level 1自动修复
- 生成Level 2修复方案
- 标记Level 3人工处理

**使用方式**：

```typescript
import { fix } from './tools/auto-fixer';

const success = await fix(analysis);
if (success) {
  console.log('✅ 修复成功');
} else {
  console.log('⚠️ 需要人工处理');
}
```

**修复Level**：
- **Level 1**：全自动修复（80%问题）
  - 添加data-testid
  - 更新选择器
  - 同步文案变更
- **Level 2**：半自动修复（15%问题）
  - API变更
  - 业务逻辑变更
  - 性能优化
- **Level 3**：人工处理（5%问题）
  - 架构问题
  - 安全问题
  - 复杂业务逻辑

---

### 5. Regression Scheduler（回归调度器）

**职责**：
- 根据修复范围选择回归策略
- 智能选择需要回归的测试用例
- 优化并行度和执行顺序

**使用方式**：

```typescript
import { createRegressionPlan } from './tools/regression-scheduler';

const plan = await createRegressionPlan(analysis, allTestCases);
console.log(`策略: ${plan.strategy}`);
console.log(`用例数: ${plan.testIds.length}`);
console.log(`预计耗时: ${plan.estimatedDuration}ms`);
```

**回归策略**：
1. **最小范围**（Level 1）：只回归失败用例本身
2. **模块范围**（Level 2）：回归同模块所有测试
3. **依赖范围**（Level 2/3）：回归依赖链上的测试
4. **全量回归**（Level 3）：回归所有测试

---

### 6. Doc Sync Checker（文档同步检查器）

**职责**：
- 检查代码与文档的一致性
- 识别需要同步的文档
- 生成文档更新建议

**使用方式**：

```typescript
import { checkDocumentSync } from './tools/doc-sync-checker';

const syncCheck = await checkDocumentSync('organization');
if (syncCheck.status === 'inconsistent') {
  console.log('⚠️ 文档不一致，需要更新');
  console.log(syncCheck.suggestedUpdates);
}
```

**检查项**：
- 前端代码 ↔ UI规范
- 后端API ↔ API文档
- 代码 ↔ 状态机文档
- 测试代码 ↔ 测试文档

---

## 配置说明

### 主配置文件

**位置**: `testing/config/test-automation.config.ts`

**关键配置**：

```typescript
export const testAutomationConfig = {
  // MCP配置
  mcp: {
    command: 'npx',
    args: ['@playwright/mcp@latest', '--browser=chromium', ...],
  },

  // 执行配置
  execution: {
    defaultTimeout: 30000,
    defaultRetryCount: 3,
    defaultParallel: 1,
  },

  // AI分析配置
  aiAnalysis: {
    enabled: true,
    autoFixLevel1: true,
    autoFixLevel2: false,
    autoFixLevel3: false,
  },

  // 回归测试配置
  regression: {
    strategySelection: {
      level1: 'minimal',
      level2: 'module',
      level3: 'full',
    },
    autoTrigger: true,
  },
};
```

### 修复模式库

**位置**: `testing/config/fix-patterns.json`

**包含10个预定义修复模式**：
- pattern-001: 添加缺失的data-testid
- pattern-002: 更新选择器
- pattern-003: 同步文案变更
- pattern-004: 更新API端点
- pattern-005: 修复等待超时
- pattern-006: 修复权限问题
- pattern-007: 修复状态流转
- pattern-008: 修复安全问题
- pattern-009: 修复架构问题
- pattern-010: 未知问题

---

## 使用示例

### 完整工作流示例

```typescript
import { executeTest } from './tools/test-executor';
import { generateReport } from './tools/report-generator';
import { analyzeFailure } from './tools/ai-analyzer';
import { fix } from './tools/auto-fixer';
import { createRegressionPlan } from './tools/regression-scheduler';

async function runAIDrivenTest(module: string) {
  console.log(`🚀 开始AI驱动测试: ${module}`);

  // 1. 执行测试
  const results = await executeTest(module, {
    environment: 'test',
    browser: 'chromium',
  });

  // 2. AI分析失败用例
  const aiAnalyses = [];
  for (const result of results.filter(r => r.status === 'failed')) {
    const analysis = await analyzeFailure(result);
    aiAnalyses.push(analysis);
  }

  // 3. 生成报告
  const report = await generateReport(context, results, aiAnalyses);
  console.log(`📊 报告已生成: ${report.artifacts.reportPath}`);

  // 4. 自动修复
  for (const analysis of aiAnalyses) {
    if (analysis.fixLevel === 'level1') {
      const success = await fix(analysis);
      if (success) {
        console.log(`✅ 自动修复成功: ${analysis.testResult.testId}`);
        
        // 5. 智能回归
        const plan = await createRegressionPlan(analysis, allTestCases);
        console.log(`🔄 触发回归测试: ${plan.strategy}`);
        // 执行回归测试...
      }
    }
  }

  console.log('✅ AI驱动测试完成');
}
```

---

## 故障排查

### 常见问题

#### 1. MCP连接失败

**错误**: `MCP进程启动失败`

**解决方法**：
```bash
# 检查Playwright MCP是否安装
npx @playwright/mcp@latest --version

# 重新安装
npm install -g @playwright/mcp@latest
```

#### 2. 测试文档解析失败

**错误**: `无法解析测试文档`

**解决方法**：
- 检查文档路径是否正确
- 确认文档格式符合模板规范
- 验证测试用例标记是否完整

#### 3. 修复失败

**错误**: `Level 1修复失败`

**解决方法**：
- 检查备份文件是否存在
- 验证文件权限
- 查看详细错误日志

#### 4. 回归测试超时

**错误**: `回归测试执行超时`

**解决方法**：
- 增加超时配置
- 减少并行度
- 检查测试环境性能

---

## 相关文档

- **[实施计划 v2](../../.agents/skills/test-backend/references/testing-standards.md)** - 完整实施计划
- **[E2E测试指南](../../.agents/skills/test-backend/references/testing-standards.md)** - 文档驱动测试编写
- **[AI修复策略](../../.agents/skills/test-backend/references/testing-standards.md)** - Level 1-3详解
- **[回归测试策略](../../.agents/skills/test-backend/references/testing-standards.md)** - 4种策略说明
- **[AI工作流](../../.agents/skills/test-backend/references/testing-standards.md)** - 完整工作流程

---

**最后更新**: 2026-01-09  
**维护者**: FFOA QA Team