niuniu/wenzi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5f5597ef0f53232f6f8111e415aa5068373c5019
wenzi/frontend/e2e/README.md

7.6 KiB
Raw Blame History

🦟 蚊子项目 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 会直接导致测试失败

凭证配置方式：

# 方式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️⃣ 一键运行（推荐）

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

这个脚本会：

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

2️⃣ 分步运行

启动后端服务

cd /path/to/mosquito
mvn spring-boot:run -Dspring-boot.run.profiles=e2e

启动前端服务

cd frontend
npm run dev -- --port 5173

运行测试

cd frontend
npm run test:e2e

📦 测试命令

# 运行所有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
  • 处理网络错误

⚙️ 配置说明

环境变量

# 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
  • 失败时自动截图和录屏

🔧 开发指南

添加新的测试用例

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客户端

// 获取活动列表
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);

认证辅助工具

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
  • 录屏: 失败测试自动录制视频

查看报告：

npm run test:e2e:report

🔍 故障排查

后端服务无法启动

# 检查端口占用
lsof -i :8080

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

前端服务无法启动

# 检查端口占用
lsof -i :5173

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

测试失败

# 使用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. 添加适当的注释说明

📞 支持

如有问题，请查看：

Reference in New Issue View Git Blame Copy Permalink