320 lines
14 KiB
Markdown
320 lines
14 KiB
Markdown
# UI 层级全自动测试套件 — 需求共识文档
|
||
|
||
> **文档编号**: GYM-GRILL-UI-TEST-001
|
||
> **日期**: 2026-07-21
|
||
> **状态**: 已确认
|
||
> **产出命令**: /grill-with-docs
|
||
|
||
---
|
||
|
||
## 一、功能概述
|
||
|
||
为健身房管理系统构建 UI 层级的全自动测试套件，覆盖 **管理后台 Web（Vue 3）** 和 **会员小程序（UniApp）** 两个 UI 终端，确保所有已实现功能通过系统化测试，达到 ≥95% 通过率的交付水平。
|
||
|
||
### 目标终端
|
||
|
||
| UI 层级 | 技术栈 | 当前测试状态 | 目标 |
|
||
|---|---|---|---|
|
||
| 管理后台 Web | Vue 3 + Element Plus + Vite | Vitest 单元测试 + Playwright E2E（81%通过率） | 修复失败 → 补齐覆盖 → ≥95% |
|
||
| 会员小程序 | UniApp（Vue） | **零测试** | 从零构建 → 完整覆盖 |
|
||
|
||
---
|
||
|
||
## 二、当前状态分析
|
||
|
||
### 2.1 已实现功能清单（管理后台 - 21个页面）
|
||
|
||
| 模块 | 页面 | 关联功能清单 | 已有 E2E Page Object | 已有 E2E 测试 |
|
||
|---|---|---|---|---|
|
||
| 系统管理 | Login / Dashboard / 403 | P0 模块7 | LoginPage / DashboardPage | ✅ |
|
||
| 系统管理 | UserManagement | P0 模块7 | UserManagementPage | ✅ journeys |
|
||
| 系统管理 | **CoachManagement** | —（额外功能） | ❌ | ❌ |
|
||
| 系统管理 | RoleManagement | P0 模块7 | RoleManagementPage | ✅ journeys |
|
||
| 系统管理 | MenuManagement | P0 模块7 | MenuManagementPage | ✅ |
|
||
| 配置 | ConfigManagement | —（额外功能） | SystemConfigPage | ✅ |
|
||
| 配置 | DictManagement | —（额外功能） | DictionaryManagementPage | ✅ |
|
||
| 文件 | FileManagement | —（额外功能） | FileManagementPage | ✅ |
|
||
| 通知 | NoticeManagement | —（额外功能） | NotificationPage | ✅ |
|
||
| 轮播图 | **BannerManagement** | —（额外功能） | ❌ | ❌ |
|
||
| 审计 | LoginLog | —（额外功能） | LoginLogPage | ✅ |
|
||
| 审计 | OperationLog | —（额外功能） | OperationLogPage | ✅ |
|
||
| 审计 | ExceptionLog | —（额外功能） | ExceptionLogPage | ✅ |
|
||
| 团课 | GroupCourseManagement | P1 模块2 | ❌ | ❌ (Page 缺失) |
|
||
| 团课 | CourseTypeManagement | P1 模块2 | ❌ | ❌ |
|
||
| 团课 | **CourseLabelManagement** | —（额外功能） | ❌ | ❌ |
|
||
| 团课 | **CourseRecommendManagement** | —（额外功能） | ❌ | ❌ |
|
||
| 会员 | **MemberManagement** | P1 模块1 | ❌ | ❌ |
|
||
| 会员 | **MemberCardManagement** | P0 模块1 | ❌ | ❌ |
|
||
| 统计 | **StatisticsDashboard** | P1 模块4 | ❌ | ❌ |
|
||
|
||
> 标记 `❌` 的为 **新增测试缺口**，共 **10 个页面**。
|
||
|
||
### 2.2 已实现功能清单（小程序 - 6个页面）
|
||
|
||
| 页面 | 关联功能清单 | 测试状态 |
|
||
|---|---|---|
|
||
| 首页 (index) | P0 模块1 微信登录入口 | ❌ |
|
||
| 登录 (login) | P0 模块1 微信快捷登录 | ❌ |
|
||
| 课程详情 (course-detail) | P0 模块2 团课详情 | ❌ |
|
||
| 我的课程 (my-courses) | P0 模块2 预约记录 | ❌ |
|
||
| 个人中心 (profile) | P0 模块1 会员信息 | ❌ |
|
||
| 搜索 (search) | P0 模块2 团课搜索 | ❌ |
|
||
|
||
### 2.3 现有测试资产
|
||
|
||
| 资产 | 状态 | 价值 |
|
||
|---|---|---|
|
||
| 12 个 Page Object | 成熟 | 可直接复用 |
|
||
| TestDataManager + TestDataFactory | 成熟 | 可直接复用 |
|
||
| RetryHelper + TestStabilityHelper | 成熟 | 可直接复用 |
|
||
| global-setup / global-teardown | 成熟 | 可直接复用 |
|
||
| customReporter（HTML+JSON+控制台） | 成熟 | 可直接复用 |
|
||
| auth.setup（storageState） | **有 Bug** | 需修复 storageState 冲突 |
|
||
| 10 个 Journey 测试（100%通过） | 健康 | 保持不变 |
|
||
|
||
### 2.4 现有失败测试分析（9个）
|
||
|
||
| 失败测试 | 根因 | 修复策略 |
|
||
|---|---|---|
|
||
| auth-test.spec.ts (4用例) | storageState 冲突：全局认证状态下，登录相关测试无法模拟未登录场景 | 为该文件配置独立 project（禁用 storageState） |
|
||
| basic-ui-test.spec.ts | 已登录后重定向到 Dashboard 而非登录页 | 调整测试预期或独立 project |
|
||
| config-management.spec.ts | 超时/选择器不匹配 | 更新选择器，增加等待策略 |
|
||
| dict-management.spec.ts | 超时/选择器不匹配 | 同上 |
|
||
| menu-management.spec.ts | 超时/选择器不匹配 | 同上 |
|
||
| debug/debug-role-assignment.spec.ts | 测试逻辑问题 | 重写或移除 |
|
||
|
||
---
|
||
|
||
## 三、用户故事
|
||
|
||
### US-1: 测试工程师运行全量回归
|
||
> As a **测试工程师**
|
||
> I want **一键运行全部 UI 测试并自动生成报告**
|
||
> So that **每次发版前能快速确认系统质量状况**
|
||
|
||
### US-2: 开发者在 CI 中获得反馈
|
||
> As a **开发者**
|
||
> I want **Push 代码后 Jenkins 自动运行冒烟测试**
|
||
> So that **核心功能回归能在 5 分钟内给出反馈**
|
||
|
||
### US-3: 产品经理验证业务规则
|
||
> As a **产品经理**
|
||
> I want **测试覆盖功能清单中的业务规则和技术要点**
|
||
> So that **交付的功能与设计一致**
|
||
|
||
### US-4: 小程序团队确保质量
|
||
> As a **小程序开发者**
|
||
> I want **微信模拟器中的自动化测试**
|
||
> So that **小程序端的回归不需要手动点点点**
|
||
|
||
---
|
||
|
||
## 四、测试架构设计
|
||
|
||
### 4.1 整体分层
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ L3: 性能测试 (Performance) │
|
||
│ - 页面加载性能 │
|
||
│ - API 响应性能 │
|
||
│ - 报告：performance-report/ │
|
||
├─────────────────────────────────────────────────┤
|
||
│ L2: 用户旅程测试 (Journey Tests) │
|
||
│ - 管理后台：按模块拆分用户旅程 │
|
||
│ - 小程序：按页面拆分用户旅程 │
|
||
│ - 报告：test-results/ + customReporter │
|
||
├─────────────────────────────────────────────────┤
|
||
│ L1: 角色边界测试 (Role Boundary) │
|
||
│ - 权限隔离验证 │
|
||
│ - 多角色并发验证 │
|
||
│ - 报告：test-results/ │
|
||
├─────────────────────────────────────────────────┤
|
||
│ L0: 冒烟测试 (Smoke) │
|
||
│ - 管理后台：登录/登出 │
|
||
│ - 小程序：启动/首页渲染 │
|
||
│ - 运行频次：每次 Push │
|
||
│ - 时限：≤ 5 分钟 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.2 技术方案
|
||
|
||
| 层级 | 管理后台 Web | 会员小程序 |
|
||
|---|---|---|
|
||
| 框架 | Playwright + TypeScript | miniprogram-automator + Jest |
|
||
| 设计模式 | Page Object | Page Object（模拟） |
|
||
| 数据管理 | TestDataManager + TestDataFactory | 独立 DataFactory（复用 API 层） |
|
||
| 报告 | customReporter（HTML+JSON） | Jest HTML Reporter |
|
||
| 运行环境 | 复用 global-setup 自动启动服务 | 微信开发者工具 CLI + 模拟器 |
|
||
| CI | Jenkins Pipeline | Jenkins Pipeline |
|
||
|
||
---
|
||
|
||
## 五、业务流程（测试范围）
|
||
|
||
### 5.1 管理后台核心流程
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[登录] --> B[Dashboard]
|
||
B --> C1[用户管理 CRUD]
|
||
B --> C2[角色管理 + 权限分配]
|
||
B --> C3[菜单管理]
|
||
C1 & C2 --> D[角色边界验证]
|
||
B --> E1[团课管理 CRUD]
|
||
B --> E2[会员管理 查看/搜索]
|
||
B --> E3[会员卡管理]
|
||
B --> E4[数据统计看板]
|
||
B --> F1[教练管理]
|
||
B --> F2[轮播图管理]
|
||
B --> F3[参数配置]
|
||
B --> F4[字典管理]
|
||
B --> F5[文件管理]
|
||
B --> F6[通知公告]
|
||
B --> F7[审计日志]
|
||
```
|
||
|
||
### 5.2 小程序核心流程
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[微信授权登录] --> B[首页]
|
||
B --> C[搜索团课]
|
||
C --> D[课程详情]
|
||
D --> E[预约课程]
|
||
B --> F[我的课程]
|
||
F --> G[取消预约]
|
||
B --> H[个人中心]
|
||
```
|
||
|
||
---
|
||
|
||
## 六、验收标准
|
||
|
||
### 通用标准
|
||
|
||
| 编号 | 标准 | 量化指标 |
|
||
|---|---|---|
|
||
| AC-1 | 测试通过率 | ≥ 95%（总用例） |
|
||
| AC-2 | 核心业务链路 | 100% 通过（登录→关键操作→退出） |
|
||
| AC-3 | 冒烟测试耗时 | ≤ 5 分钟 |
|
||
| AC-4 | 全量 E2E 耗时 | ≤ 15 分钟（管理后台 + 小程序并行） |
|
||
| AC-5 | 测试报告 | 自动生成 HTML + JSON 报告，包含失败截图 |
|
||
| AC-6 | CI 集成 | Jenkins Pipeline 可一键触发，结果自动归档 |
|
||
| AC-7 | 测试数据隔离 | 每次运行使用独立数据前缀，运行后自动清理 |
|
||
| AC-8 | 稳定性 | 连续 3 次无随机失败（flake rate = 0%） |
|
||
|
||
### 功能覆盖标准
|
||
|
||
| 编号 | 标准 |
|
||
|---|---|
|
||
| AC-9 | 管理后台 21 个页面，每个至少 1 个 Happy Path 测试 |
|
||
| AC-10 | 核心 CRUD 操作（用户/角色/团课）覆盖增删改查全流程 |
|
||
| AC-11 | 角色边界测试覆盖至少 3 个角色（Admin / 店长 / 前台） |
|
||
| AC-12 | 小程序 6 个页面，每个至少 1 个 Happy Path 测试 |
|
||
| AC-13 | 小程序预约/取消流程端到端验证 |
|
||
| AC-14 | 性能测试至少覆盖 Dashboard 和团课列表 2 个关键页面 |
|
||
|
||
---
|
||
|
||
## 七、实施计划（优先级排序）
|
||
|
||
### 第1阶段：修复现有测试（预计 1 天）
|
||
|
||
| 任务 | 产出 |
|
||
|---|---|
|
||
| 修复 storageState 冲突 | auth-test.spec.ts 4 个用例通过 |
|
||
| 为需要未登录状态的测试创建独立 Playwright project | basic-ui-test.spec.ts 通过 |
|
||
| 更新选择器 + 等待策略 | config/dict/menu 3 个 spec 通过 |
|
||
| 处理 debug 目录 | 重写或移除 debug-role-assignment |
|
||
| **目标** | 53/53 测试通过（100%） |
|
||
|
||
### 第2阶段：补齐管理后台缺失测试（预计 2 天）
|
||
|
||
| 任务 | 覆盖页面 |
|
||
|---|---|
|
||
| 创建 10 个新 Page Object | CoachManagement, BannerManagement, GroupCourseManagement, CourseTypeManagement, CourseLabelManagement, CourseRecommendManagement, MemberManagement, MemberCardManagement, StatisticsDashboard（以及团课页面类） |
|
||
| 编写 8 个 Journey 测试 | 对应上述缺失页面 |
|
||
| 扩展角色边界测试 | 3 角色 × 5 关键页面 |
|
||
| 编写 2 个性能测试 | Dashboard + 团课列表 |
|
||
|
||
### 第3阶段：构建小程序测试（预计 2 天）
|
||
|
||
| 任务 | 产出 |
|
||
|---|---|
|
||
| 搭建 miniprogram-automator 环境 | 安装依赖、配置微信开发者工具 CLI |
|
||
| 创建小程序 Page Object（6 个页面） | 首页/登录/课程详情/我的课程/个人中心/搜索 |
|
||
| 编写 4 个 Journey 测试 | 登录→首页→课程详情→预约；登录→我的课程→取消；登录→个人中心→信息编辑；首页→搜索→课程详情 |
|
||
| 编写 1 个冒烟测试 | 启动→首页渲染→登录 |
|
||
|
||
### 第4阶段：Jenkins CI 集成（预计 1 天）
|
||
|
||
| 任务 | 产出 |
|
||
|---|---|
|
||
| 编写 Jenkinsfile | 定义 Stage：环境准备 → 冒烟测试 → 全量 E2E（Web + 小程序并行） → 性能测试 → 报告归档 |
|
||
| 配置测试报告归档 | HTML Report Plugin + JUnit Plugin |
|
||
| 配置失败通知 | 企业微信/邮件通知 |
|
||
|
||
---
|
||
|
||
## 八、涉及的领域概念
|
||
|
||
| 领域概念 | 测试关注点 |
|
||
|---|---|
|
||
| 会员 (Member) | 会员管理 CRUD、会员卡购买/查看 |
|
||
| 用户 (User) | 用户管理 CRUD、角色分配 |
|
||
| 角色 (Role) | 角色 CRUD、权限分配、边界验证 |
|
||
| 权限 (Permission) | 菜单可见性、按钮权限、越权访问验证 |
|
||
| 团课 (Group Course) | 团课 CRUD、类型/标签/推荐管理 |
|
||
| 预约 (Booking) | 预约/取消流程（小程序端） |
|
||
| 签到 (Check-in) | 扫码签到（后续迭代，依赖微信环境） |
|
||
| 会员卡 (Membership Card) | 会员卡管理、到期提醒 |
|
||
|
||
---
|
||
|
||
## 九、非功能需求
|
||
|
||
| 类型 | 要求 |
|
||
|---|---|
|
||
| **可靠性** | 连续 3 次运行无随机失败（flake-free） |
|
||
| **可维护性** | Page Object 模式，禁止硬编码选择器 |
|
||
| **可扩展性** | 新页面通过添加 Page Object + 1 个 Journey 即可接入 |
|
||
| **数据隔离** | 测试数据使用唯一前缀，运行后自动清理，不影响开发环境 |
|
||
| **CI 兼容** | Jenkins Pipeline 声明式，参数化（支持选择运行范围） |
|
||
|
||
---
|
||
|
||
## 十、风险与应对
|
||
|
||
| 风险 | 应对策略 |
|
||
|---|---|
|
||
| miniprogram-automator 与 UniApp 兼容性问题 | 先用 H5 模式验证可行性，再切换模拟器 |
|
||
| 微信开发者工具在 Jenkins 无头环境运行受限 | Jenkins Agent 部署在 Windows 有桌面环境机器上 |
|
||
| 现有 E2E 测试大规模重构引入回归 | 第1阶段仅修复，不做重构；后续新增测试在独立文件中 |
|
||
| 小程序登录依赖真实微信环境 | 使用 Mock 微信 API 或测试用 OpenID/UnionID |
|
||
| 性能测试基准不稳定 | 取 3 次运行中位数，允许 ±15% 波动 |
|
||
|
||
---
|
||
|
||
## 十一、待确认项
|
||
|
||
- [x] UI 层级范围：管理后台 + 小程序
|
||
- [x] 功能范围：全部已实现功能，对齐功能清单业务规则
|
||
- [x] 交付标准：≥95% 通过率 + Jenkins CI
|
||
- [x] 测试类型：E2E / 冒烟 / 性能 / 角色边界 / 小程序专项
|
||
- [x] 小程序方案：miniprogram-automator
|
||
- [x] CI 平台：Jenkins
|
||
- [x] 测试环境：复用 global-setup
|
||
- [x] 优先级：修复现有 → 补齐 Web → 构建小程序 → CI
|
||
- [x] 用户体验测试 (UAT)：**不纳入**，聚焦自动化测试，UAT 由人工执行
|
||
- [x] 视觉回归测试：**不纳入**，避免基准截图频繁更新的维护成本
|
||
|
||
---
|
||
|
||
## 十二、相关文档
|
||
|
||
- [CONTEXT.md](../../../CONTEXT.md) — 项目领域术语表
|
||
- [基础版功能清单.md](../../../基础版功能清单.md) — 功能清单与业务规则
|
||
- [AGENT.md](../../../AGENT.md) — AI 协作工作流规范
|