wenzi/frontend/e2e/README.md

# 🦟 蚊子项目 E2E端到端测试

## 📋 概述

本项目使用 **Playwright** 进行真正的端到端测试，与现有的Cypress Mock测试不同，这些测试会与真实的后端API进行交互，验证前后端的一致性。

## 🎯 测试特点

- ✅ **真实API交互** - 不Mock后端，调用真实的蚊子后端服务
- ✅ **前后端一致性验证** - 同时启动前后端，验证完整业务流程
- ✅ **多浏览器支持** - Chromium、Firefox、WebKit
- ✅ **移动端测试** - 支持多种移动设备模拟
- ✅ **自动截图和录屏** - 失败时自动记录证据
- ✅ **并行执行** - 提高测试效率

## 🚀 快速开始

### 0️⃣ 双模式执行说明

E2E 测试支持两种执行模式：

**模式一：无真实凭证（默认/demo模式）**
- 测试会检测到使用了默认测试凭证
- API 测试会显式跳过（`test.skip`），只运行页面相关测试
- 不会因为后端服务未启动而失败

**模式二：有真实凭证（严格模式）**
- 需要提供真实的 API Key 和 User Token
- 所有 API 测试会严格断言 2xx/3xx 响应码
- 401/403/404 会直接导致测试失败

凭证配置方式：
```bash
# 方式1：设置环境变量
export E2E_USER_TOKEN="your-real-user-token"
export API_BASE_URL="http://your-backend:8080"
export PLAYWRIGHT_BASE_URL="http://your-frontend:5173"

# 方式2：创建 .e2e-test-data.json 文件
# 位置：frontend/e2e/.e2e-test-data.json
# 内容：
# {
#   "apiKey": "your-real-api-key",
#   "userToken": "your-real-user-token",
#   "activityId": 1,
#   "userId": 10001
# }
```

### 1️⃣ 一键运行（推荐）

```bash
# 使用启动脚本（自动启动前后端并运行测试）
cd frontend
./scripts/run-e2e-tests.sh
```

这个脚本会：
1. 编译后端Spring Boot应用
2. 启动后端服务（端口8080）
3. 启动前端开发服务器（端口5173）
4. 等待服务就绪
5. 运行Playwright E2E测试
6. 自动清理进程

### 2️⃣ 分步运行

#### 启动后端服务
```bash
cd /path/to/mosquito
mvn spring-boot:run -Dspring-boot.run.profiles=e2e
```

#### 启动前端服务
```bash
cd frontend
npm run dev -- --port 5173
```

#### 运行测试
```bash
cd frontend
npm run test:e2e
```

## 📦 测试命令

```bash
# 运行所有E2E测试
npm run test:e2e

# 使用UI模式运行（可视化调试）
npm run test:e2e:ui

# 调试模式
npm run test:e2e:debug

# 查看测试报告
npm run test:e2e:report

# 安装Playwright浏览器
npm run test:e2e:install

# 运行Cypress测试（已有的Mock测试）
npm run test:cypress
```

## 🗂️ 测试结构

```
frontend/e2e/
├── global-setup.ts          # 全局设置：创建测试数据
├── global-teardown.ts       # 全局清理：删除测试数据
├── fixtures/
│   └── test-data.ts         # 测试夹具和API客户端
├── tests/
│   └── user-journey.spec.ts # 用户旅程测试用例
├── utils/
│   ├── auth-helper.ts       # 认证辅助工具
│   └── wait-helper.ts       # 等待辅助工具
└── results/                 # 测试结果截图和录屏
```

## 🧪 测试场景

### 用户核心旅程
1. **首页加载和活动列表展示**
   - 验证页面加载
   - 验证活动列表API返回数据

2. **活动详情和统计数据展示**
   - 获取活动详情API
   - 获取活动统计数据API
   - 前端页面展示验证

3. **排行榜查看流程**
   - 获取排行榜数据API
   - 前端展示验证

4. **短链生成和访问流程**
   - 生成短链API
   - 访问短链跳转
   - 验证点击记录

5. **分享统计数据查看**
   - 获取分享统计API
   - 前端展示验证

6. **API Key验证流程**
   - 验证有效的API Key

### 响应式布局测试
- 移动端布局（375x667）
- 平板端布局（768x1024）
- 桌面端布局（1920x1080）

### 性能测试
- API响应时间（<2秒）
- 页面加载时间（<5秒）

### 错误处理测试
- 处理无效的活动ID
- 处理网络错误

## ⚙️ 配置说明

### 环境变量

```bash
# API基础地址
export API_BASE_URL=http://localhost:8080

# 前端基础地址
export PLAYWRIGHT_BASE_URL=http://localhost:5173
```

### Playwright配置

主要配置项在 `playwright.config.ts`：
- 并行执行：开启
- 重试次数：CI环境2次，本地1次
- 浏览器：Chromium、Firefox、WebKit
- 移动端：Pixel 5、iPhone 12
- 失败时自动截图和录屏

## 🔧 开发指南

### 添加新的测试用例

```typescript
import { test, expect } from '../fixtures/test-data';

test('你的测试场景', async ({ page, testData, apiClient }) => {
  await test.step('步骤1', async () => {
    // API调用
    const response = await apiClient.getActivity(testData.activityId);
    expect(response.code).toBe(200);
  });

  await test.step('步骤2', async () => {
    // 页面操作
    await page.goto(`/?activityId=${testData.activityId}`);
    await expect(page).toHaveTitle(/蚊子/);
  });
});
```

### 使用API客户端

```typescript
// 获取活动列表
const activities = await apiClient.getActivities();

// 获取活动详情
const activity = await apiClient.getActivity(activityId);

// 获取统计数据
const stats = await apiClient.getActivityStats(activityId);

// 获取排行榜
const leaderboard = await apiClient.getLeaderboard(activityId, 0, 10);

// 创建短链
const shortLink = await apiClient.createShortLink(originalUrl, activityId);

// 获取分享指标
const metrics = await apiClient.getShareMetrics(activityId);
```

### 认证辅助工具

```typescript
import { setAuthenticated, setApiKey } from '../utils/auth-helper';

// 设置用户登录状态
await setAuthenticated(page, userId);

// 设置API Key
await setApiKey(page, apiKey);
```

## 📊 测试报告

测试完成后，会生成以下报告：

- **HTML报告**: `frontend/e2e/e2e-report/index.html`
- **JUnit报告**: `frontend/e2e/e2e-results.xml`
- **截图**: `frontend/e2e/e2e-results/*.png`
- **录屏**: 失败测试自动录制视频

查看报告：
```bash
npm run test:e2e:report
```

## 🔍 故障排查

### 后端服务无法启动
```bash
# 检查端口占用
lsof -i :8080

# 查看后端日志
tail -f /tmp/mosquito-backend.log
```

### 前端服务无法启动
```bash
# 检查端口占用
lsof -i :5173

# 查看前端日志
tail -f /tmp/mosquito-frontend.log
```

### 测试失败
```bash
# 使用UI模式调试
npm run test:e2e:ui

# 查看详细日志
npm run test:e2e -- --reporter=list
```

## 🆚 Playwright vs Cypress

| 特性 | Playwright (新) | Cypress (已有) |
|------|----------------|---------------|
| API交互 | ✅ 真实API | ⚠️ Mock API |
| 多浏览器 | ✅ Chromium/Firefox/WebKit | ⚠️ Electron/Firefox |
| 并行执行 | ✅ 原生支持 | ⚠️ 商业版 |
| 移动端 | ✅ 内置支持 | ⚠️ 有限支持 |
| 调试体验 | ⚠️ 一般 | ✅ 优秀 |
| 社区生态 | ⚠️ 新兴 | ✅ 成熟 |

**建议**：使用Playwright进行真实API的集成测试，保留Cypress进行前端组件的Mock测试。

## 📝 注意事项

1. **测试数据隔离** - 每次测试运行使用独立的活动和API Key
2. **自动清理** - 测试结束后自动清理测试数据
3. **环境依赖** - 需要Node.js、npm、Maven、Java环境
4. **端口占用** - 确保8080和5173端口未被占用

## 🤝 贡献指南

添加新测试时，请遵循：
1. 使用 `test.step` 组织测试步骤
2. 每个测试独立，不依赖其他测试
3. 使用有意义的测试名称（中文描述场景）
4. 失败时自动截图记录
5. 添加适当的注释说明

## 📞 支持

如有问题，请查看：
- [Playwright文档](https://playwright.dev/)
- 项目README
- 后端API文档