299 lines
12 KiB
Markdown
299 lines
12 KiB
Markdown
# Web 后台管理系统 — 测试文档
|
||
|
||
> **位置**: `gym-manage-web/` | **框架**: Vitest + Playwright | **用例数**: 185+ (单元 171 + E2E 14+) | **通过率**: 100%
|
||
|
||
---
|
||
|
||
## 一、概览
|
||
|
||
Web 后台管理系统有两层测试体系：
|
||
|
||
| 测试类型 | 框架 | 用例数 | 通过率 | 运行命令 |
|
||
|---|---|---|---|---|
|
||
| **单元测试** | Vitest + jsdom | 171 | 100% | `npm run test` |
|
||
| **E2E 测试** | Playwright | 24+（按需指定）| 100% | `npm run test:e2e` |
|
||
|
||
---
|
||
|
||
## 二、Vitest 单元测试（24 文件，171 用例）
|
||
|
||
### 2.1 组件测试（13 文件，141 用例）
|
||
|
||
覆盖所有管理页面的 Vue 组件渲染和行为。
|
||
|
||
| 测试文件 | 用例数 | 测试的 Vue 组件 |
|
||
|---|---|---|
|
||
| `Login.test.ts` | 12 | 登录表单（用户名/密码输入、提交、错误提示、记住我） |
|
||
| `Dashboard.test.ts` | 10 | 仪表盘（统计卡片、数据加载、模块渲染） |
|
||
| `UserManagement.test.ts` | 15 | 用户管理（列表渲染、搜索、新增/编辑对话框、角色分配、删除确认） |
|
||
| `RoleManagement.test.ts` | 12 | 角色管理（列表、权限树、菜单分配、状态切换） |
|
||
| `MenuManagement.test.ts` | 14 | 菜单管理（树形表格、新增/编辑、图标选择、排序） |
|
||
| `DictManagement.test.ts` | 12 | 字典管理（类型+数据 Tab切换、新增、编辑、删除） |
|
||
| `ConfigManagement.test.ts` | 10 | 参数配置（列表、新增、编辑、key 唯一性） |
|
||
| `NoticeManagement.test.ts` | 10 | 通知公告（发布、撤回、富文本编辑） |
|
||
| `FileManagement.test.ts` | 8 | 文件管理（上传、下载、预览、删除、类型过滤） |
|
||
| `OperationLog.test.ts` | 8 | 操作日志（列表、筛选、详情查看） |
|
||
| `LoginLog.test.ts` | 8 | 登录日志（列表、状态筛选、时间范围） |
|
||
| `ExceptionLog.test.ts` | 7 | 异常日志（列表、堆栈展开、级别过滤） |
|
||
| `MenuItem.test.ts` | 5 | 菜单项渲染、路由跳转、权限隐藏 |
|
||
|
||
### 2.2 状态管理（1 文件，10 用例）
|
||
|
||
| 测试文件 | 用例数 | 测试内容 |
|
||
|---|---|---|
|
||
| `permission.test.ts` | 10 | Pinia Permission Store：`setPermissions`/`clearPermissions`、`hasRole`/`hasPermission`、空权限处理、管理员特殊处理 |
|
||
|
||
### 2.3 指令（1 文件，5 用例）
|
||
|
||
| 测试文件 | 用例数 | 测试内容 |
|
||
|---|---|---|
|
||
| `permission.test.ts` | 5 | `v-permission` 指令：角色检查、权限检查、数组参数、无权限隐藏/禁用 |
|
||
|
||
### 2.4 路由守卫（1 文件，5 用例）
|
||
|
||
| 测试文件 | 用例数 | 测试内容 |
|
||
|---|---|---|
|
||
| `permission.guard.test.ts` | 5 | 未登录 → 重定向 `/login`、已登录访问 `/login` → 重定向 `/dashboard`、Token过期处理、白名单路径、动态路由加载 |
|
||
|
||
### 2.5 基于角色的测试（3 文件，15 用例）
|
||
|
||
| 测试文件 | 用例数 | 测试内容 |
|
||
|---|---|---|
|
||
| `admin.role.test.ts` | 6 | 管理员角色：全权限、全菜单、无限制操作 |
|
||
| `base.role.test.ts` | 5 | 基础角色：受限菜单、操作按钮隐藏 |
|
||
| `role-factory.test.ts` | 4 | 角色工厂：动态创建测试角色、权限组合 |
|
||
|
||
### 2.6 角色测试辅助（3 文件，13 用例）
|
||
|
||
| 测试文件 | 用例数 | 测试内容 |
|
||
|---|---|---|
|
||
| `test-data-manager.test.ts` | 5 | 测试数据生成器（用户、角色、菜单） |
|
||
| `role-auth-manager.test.ts` | 4 | 角色认证管理器 |
|
||
| `permission-helper.test.ts` | 4 | 权限辅助工具 |
|
||
|
||
### 2.7 工具函数（1 文件，6 用例）
|
||
|
||
| 测试文件 | 用例数 | 测试内容 |
|
||
|---|---|---|
|
||
| `errorHandler.test.ts` | 6 | 统一错误处理：网络错误、401 自动登出、403 提示、超时回调 |
|
||
|
||
### 2.8 配置验证（1 文件，2 用例）
|
||
|
||
| 测试文件 | 用例数 | 测试内容 |
|
||
|---|---|---|
|
||
| `config.test.ts` | 2 | Vitest 框架配置验证：基础断言、异步支持 |
|
||
|
||
### 2.9 Vitest 单元测试目录结构
|
||
|
||
```
|
||
src/__tests__/
|
||
├── components/ # 14 组件测试
|
||
│ ├── Login.test.ts
|
||
│ ├── Dashboard.test.ts
|
||
│ ├── UserManagement.test.ts
|
||
│ ├── RoleManagement.test.ts
|
||
│ ├── MenuManagement.test.ts
|
||
│ ├── MenuItem.test.ts
|
||
│ ├── DictManagement.test.ts
|
||
│ ├── ConfigManagement.test.ts
|
||
│ ├── NoticeManagement.test.ts
|
||
│ ├── FileManagement.test.ts
|
||
│ ├── OperationLog.test.ts
|
||
│ ├── LoginLog.test.ts
|
||
│ └── ExceptionLog.test.ts
|
||
├── stores/
|
||
│ └── permission.test.ts # Pinia Store
|
||
├── directives/
|
||
│ └── permission.test.ts # v-permission
|
||
├── router/
|
||
│ └── permission.guard.test.ts # 路由守卫
|
||
├── utils/
|
||
│ └── errorHandler.test.ts # 错误处理
|
||
├── config.test.ts # 框架验证
|
||
└── role-based-tests/ # 基于角色
|
||
├── roles/__tests__/
|
||
│ ├── admin.role.test.ts
|
||
│ ├── base.role.test.ts
|
||
│ └── role-factory.test.ts
|
||
└── shared/__tests__/
|
||
├── test-data-manager.test.ts
|
||
├── role-auth-manager.test.ts
|
||
└── permission-helper.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
## 三、Playwright E2E 测试（24+ 用例）
|
||
|
||
### 3.1 测试体系
|
||
|
||
由 4 个项目组成，分别覆盖不同层级：
|
||
|
||
| 项目 | 目录 | 描述 | 用例数 |
|
||
|---|---|---|---|
|
||
| `setup` | `auth.setup.ts` | 认证 Token 预获取（全局前置） | 1 |
|
||
| `smoke` | `e2e/smoke/` | 基础冒烟测试 | 1 |
|
||
| `root` | `e2e/*.spec.ts` | 独立功能验证 | 7 |
|
||
| `journeys` | `e2e/journeys/` | 端到端旅程 | 16 |
|
||
| `debug` | `e2e/debug/` | 调试辅助 | 3 |
|
||
|
||
### 3.2 运行命令
|
||
|
||
```bash
|
||
npm run test:e2e # 全部项目
|
||
npm run test:e2e:smoke # 冒烟测试
|
||
npm run test:e2e:journeys # 旅程测试
|
||
npm run test:e2e:headed # 有头模式（可视化）
|
||
npm run test:e2e:debug # 调试模式（逐步执行）
|
||
npm run test:e2e:perf # 性能基准
|
||
```
|
||
|
||
### 3.3 配置参数
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|---|---|---|
|
||
| baseURL | `http://localhost:3002` | Web 前端地址 |
|
||
| timeout | 120s | 测试超时 |
|
||
| expect.timeout | 30s | 断言超时 |
|
||
| actionTimeout | 30s | 操作超时 |
|
||
| navigationTimeout | 60s | 页面跳转超时 |
|
||
| retries | CI: 2, 本地: 1 | 失败重试次数 |
|
||
| workers | CI: 4, 本地: 50% | 并行 Worker 数 |
|
||
| headless | CI: true, 本地: false | 无头模式 |
|
||
| viewport | 1280×720 | 浏览器窗口 |
|
||
| locale | zh-CN | 语言 |
|
||
| slowMo | CI: 0, 本地: 100ms | 操作延迟 |
|
||
|
||
### 3.4 测试文件详情
|
||
|
||
#### 冒烟测试 (smoke/)
|
||
|
||
| 文件 | 用例数 | 测试内容 |
|
||
|---|---|---|
|
||
| `login-logout.spec.ts` | 1 | 管理员登录 → 导航验证 → 登出 |
|
||
|
||
#### 根级测试
|
||
|
||
| 文件 | 用例数 | 测试内容 |
|
||
|---|---|---|
|
||
| `api-connectivity.spec.ts` | 3 | 网关健康检查 `/actuator/health`、前端页面加载、数据库连接状态 |
|
||
| `auth-test.spec.ts` | 3 | JWT Token 获取/验证、未授权 401、登录 UI、权限验证 |
|
||
| `basic-ui-test.spec.ts` | 1 | 首页加载、登录页表单元素、导航栏、响应式 (375×667) |
|
||
| `unauthorized-redirect.spec.ts` | 1 | 未登录访问 `/members`、`/courses`、`/statistics` → 自动重定向 `/login` |
|
||
| `menu-management.spec.ts` | 1 | 登录 → 菜单管理 → 表格数据渲染 |
|
||
| `dict-management.spec.ts` | 1 | 登录 → 字典管理 → 类型+数据列表 |
|
||
| `config-management.spec.ts` | 1 | 登录 → 参数配置 → 列表显示 |
|
||
|
||
#### 旅程测试 (journeys/)
|
||
|
||
| 文件 | 用例数 | 业务链路 |
|
||
|---|---|---|
|
||
| `admin-complete-workflow.spec.ts` | 1 | 创建角色 → 分配权限 → 创建用户 → 绑定角色 → 验证权限 |
|
||
| `audit-workflow.spec.ts` | 1 | 导航审计日志 → 筛选条件 → 时间范围 → 详情查看 |
|
||
| `coach-banner-workflow.spec.ts` | 1 | 教练管理 → 轮播图管理 → 新增/编辑 |
|
||
| `config-workflow.spec.ts` | 1 | 参数配置 → 新增配置 → 编辑 → 删除 |
|
||
| `dict-workflow.spec.ts` | 1 | 字典类型创建 → 字典数据录入 → 编辑 → 删除 |
|
||
| `dictionary-complete-workflow.spec.ts` | 1 | 字典类型+数据完整增删改查流程 |
|
||
| `exception-log-workflow.spec.ts` | 1 | 异常日志查看 → 堆栈展开 → 级别筛选 |
|
||
| `extended-role-boundary.spec.ts` | 1 | 角色权限扩展 → 边界条件 → 多角色叠加 |
|
||
| `file-management-workflow.spec.ts` | 1 | 文件上传 → 列表查看 → 下载 → 预览 → 删除 |
|
||
| `groupcourse-workflow.spec.ts` | 1 | 课程类型 → 课程标签 → 课程推荐 → 团课管理 |
|
||
| `member-workflow.spec.ts` | 1 | 会员列表 → 会员卡管理 → 储值卡 → 退款申请 |
|
||
| `notice-workflow.spec.ts` | 1 | 创建公告 → 发布 → 查看 → 撤回 |
|
||
| `performance.spec.ts` | 1 | 首屏加载时间、路由切换性能、API 响应耗时 |
|
||
| `statistics-workflow.spec.ts` | 1 | 数据统计看板 → 会员统计 → 预约统计 → 签到统计 |
|
||
| `system-config-complete-workflow.spec.ts` | 1 | 系统配置完整增删改查 → 缓存刷新 → 验证生效 |
|
||
| `user-permission-boundary.spec.ts` | 1 | 普通用户权限边界 → 受限菜单 → 按钮隐藏 → 403 处理 |
|
||
|
||
---
|
||
|
||
## 四、Page Object 模式（11 个页面对象）
|
||
|
||
所有页面交互封装在 `e2e/pages/` 下：
|
||
|
||
| Page Object | 对应页面 | 核心方法 |
|
||
|---|---|---|
|
||
| `LoginPage.ts` | 登录 | `goto()`, `login(username, password)`, `getErrorMessage()` |
|
||
| `DashboardPage.ts` | 仪表盘 | `getStats()`, `navigateTo(menu)` |
|
||
| `UserManagementPage.ts` | 用户管理 | `searchUser()`, `addUser()`, `editUser()`, `deleteUser()` |
|
||
| `RoleManagementPage.ts` | 角色管理 | `addRole()`, `assignPermissions()`, `toggleStatus()` |
|
||
| `MenuManagementPage.ts` | 菜单管理 | `addMenu()`, `editMenu()`, `deleteMenu()`, `getTree()` |
|
||
| `DictionaryManagementPage.ts` | 字典管理 | `addType()`, `addData()`, `editData()`, `deleteData()` |
|
||
| `SystemConfigPage.ts` | 参数配置 | `addConfig()`, `editConfig()`, `deleteConfig()` |
|
||
| `NotificationPage.ts` | 通知公告 | `createNotice()`, `publish()`, `revoke()` |
|
||
| `FileManagementPage.ts` | 文件管理 | `uploadFile()`, `downloadFile()`, `previewFile()` |
|
||
| `OperationLogPage.ts` | 操作日志 | `filterByModule()`, `viewDetail()` |
|
||
| `LoginLogPage.ts` | 登录日志 | `filterByStatus()`, `filterByDate()` |
|
||
| `ExceptionLogPage.ts` | 异常日志 | `expandStack()`, `filterByLevel()` |
|
||
|
||
### 业务 Page Object（6 个）
|
||
|
||
| Page Object | 用途 |
|
||
|---|---|
|
||
| `CoachManagementPage.ts` | 教练 CRUD |
|
||
| `BannerManagementPage.ts` | 轮播图管理 |
|
||
| `CourseTypeManagementPage.ts` | 课程类型管理 |
|
||
| `CourseLabelManagementPage.ts` | 课程标签管理 |
|
||
| `CourseRecommendManagementPage.ts` | 课程推荐管理 |
|
||
| `GroupCourseManagementPage.ts` | 团课管理 |
|
||
| `MemberManagementPage.ts` | 会员管理 |
|
||
| `MemberCardManagementPage.ts` | 会员卡管理 |
|
||
| `StatisticsDashboardPage.ts` | 统计看板 |
|
||
|
||
---
|
||
|
||
## 五、辅助模块
|
||
|
||
### Helpers
|
||
|
||
| 文件 | 用途 |
|
||
|---|---|
|
||
| `auth.ts` | 登录认证、Token 存储/获取/清除 |
|
||
| `TestStabilityHelper.ts` | 测试稳定性（重试、等待、超时处理） |
|
||
| `TestDataManager.ts` | 测试数据 CRUD 管理 |
|
||
|
||
### Utils
|
||
|
||
| 文件 | 用途 |
|
||
|---|---|
|
||
| `api-client.ts` | HTTP API 客户端封装 |
|
||
| `testHelper.ts` | 通用测试辅助函数 |
|
||
| `TestDataFactory.ts` | 测试数据工厂（用户/角色/菜单/字典生成） |
|
||
| `TestDataCleanup.ts` | 测试后数据清理 |
|
||
| `RetryHelper.ts` | 智能重试策略 |
|
||
| `testDataManager.ts` | 测试数据管理 |
|
||
|
||
### Fixtures
|
||
|
||
| 文件 | 用途 |
|
||
|---|---|
|
||
| `test-data.ts` | 静态测试数据（账号、权限、菜单结构） |
|
||
| `test-file.txt` | 文件上传测试用文件 |
|
||
|
||
---
|
||
|
||
## 六、运行方式
|
||
|
||
```bash
|
||
# 进入 Web 后台目录
|
||
cd gym-manage-web
|
||
|
||
# 单元测试
|
||
npm run test # 全量单元测试
|
||
npx vitest --run # 同全量
|
||
npx vitest --run Login # 运行匹配 "Login" 的测试
|
||
npx vitest --ui # Vitest UI 模式
|
||
|
||
# E2E 测试（需先启动后端和前端服务）
|
||
npm run test:e2e # 全部 Playwright 项目
|
||
npm run test:e2e:smoke # 仅冒烟
|
||
npm run test:e2e:journeys # 仅旅程
|
||
npm run test:e2e:headed # 可视化浏览器
|
||
npm run test:e2e:debug # 逐步执行
|
||
npm run test:e2e:perf # 性能基准
|
||
```
|
||
|
||
---
|
||
|
||
**文档生成时间**: 2026-07-21 | **测试工具**: Vitest + jsdom / Playwright + Chromium
|