320 lines
7.6 KiB
Markdown
320 lines
7.6 KiB
Markdown
# 🦟 蚊子项目 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文档
|