# 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