# 📋 WaveControl 隔空手势控制系统 - 测试文档

## 一、测试概述

### 1.1 测试目标

确保系统三个核心子模块功能完整、交互稳定、性能可靠，满足多场景下的非接触式人机交互需求，包括主控制平台、手语通平台、游戏控制模块。

### 1.2 测试对象

- 主控制系统（控制面板 + 手势库管理 + 语音识别）
- WaveSign 手语通系统（教学、评分、社区）
- 虚拟赛车手柄系统（游戏中控制响应）

### 1.3 测试类型

| 测试类型     | 说明                                       |
| ------------ | ------------------------------------------ |
| 功能测试     | 各模块是否能完成核心功能                   |
| 集成测试     | 各子模块之间的数据流与交互是否正确         |
| 性能测试     | 系统是否在高帧率下稳定运行、响应及时       |
| 边界测试     | 识别模糊手势、断网、摄像头断连等异常情况   |
| 用户体验测试 | 普通用户是否能流畅使用、易上手、有清晰反馈 |



## 二、测试环境

| 项目        | 配置                              |
| ----------- | --------------------------------- |
| 操作系统    | Windows 10 / 11、MacOS            |
| Python 版本 | Python 3.8+                       |
| 浏览器      | Chrome / Edge                     |
| 识别设备    | USB 外接摄像头 / 笔记本自带摄像头 |
| 游戏平台    | Steam 平台《Rush Rally Origins》  |



## 三、测试用例设计

### ✅ 主控制系统

| 序号 | 手势名称     | 手势动作说明                                  | 所属类型 |
| ---- | ------------ | --------------------------------------------- | -------- |
| 01   | 光标控制     | 竖起食指滑动控制光标位置                      | 通用控制 |
| 02   | 鼠标左键点击 | 食指 + 大拇指上举执行点击                     | 通用控制 |
| 03   | 滚动控制     | okay 手势（食指+拇指捏合），上下移动滚动页面  | 通用控制 |
| 04   | 全屏控制     | 四指并拢向上 → 触发设定键（默认 f 键）        | 通用控制 |
| 05   | 退格         | 特定手势触发退格键                            | 通用控制 |
| 06   | 开始语音识别 | 六指手势触发语音识别启动                      | 通用控制 |
| 07   | 结束语音识别 | 拳头手势触发语音识别停止                      | 通用控制 |
| 08   | 暂停/继续    | 单手张开保持 1.5 秒触发暂停/继续识别          | 通用控制 |
| 09   | 向右移动     | 拇指上抬，其余手指收回 → 控制游戏角色向右移动 | 游戏控制 |
| 10   | 跳跃         | 食指、中指上举 → 控制跳跃动作                 | 游戏控制 |
| 11   | 右跳跃       | 拇指 + 食指 + 中指上举 → 控制右跳跃           | 游戏控制 |
| 12   | 上一首       | 大拇指向左摆动 → 上一首音乐                   | 音乐控制 |
| 13   | 下一首       | 大拇指向右摆动 → 下一首音乐                   | 音乐控制 |
| 14   | 暂停/播放    | 比耶手势（✌️ or 🤘） → 暂停或播放音乐           | 音乐控制 |
| 15   | 切换音乐模式 | rock 手势（🤘）→ 切换音乐/普通控制模式         | 模式切换 |



### 🤟 手语通 WaveSign

#### ✅ 1. **SLClassroom（手语教室）模块**

| 用例编号 | 用例名称           | 测试点                      | 预期结果                    |
| -------- | ------------------ | --------------------------- | --------------------------- |
| TC-SL-01 | 摄像头实时识别     | 摄像头接通后手势是否被识别  | 返回手语内容 + 实时评分动画 |
| TC-SL-02 | 视频上传评分       | 上传手语视频后是否正常评分  | 返回分数、标准建议          |
| TC-SL-03 | 视频课程学习流程   | 是否能顺序播放、标记已学    | 视频播放正常，课程解锁      |
| TC-SL-04 | 翻转卡片练习       | 卡片是否翻转 + 显示正确答案 | 点击翻面后显示预设解释      |
| TC-SL-05 | 任务式课程地图跳转 | 点击课程节点是否正确跳转    | 跳转至对应课程页            |



#### ✅ 2. **Community（社区系统）模块**

| 用例编号  | 用例名称      | 测试点                     | 预期结果                   |
| --------- | ------------- | -------------------------- | -------------------------- |
| TC-COM-01 | 发帖功能      | 输入文字/图片/视频发帖     | 帖子成功展示 + ID 唯一标识 |
| TC-COM-02 | 评论功能      | 帖子下评论 + 删除          | 评论正常显示/删除          |
| TC-COM-03 | 点赞机制      | 点赞后数值变化             | 点赞数+1，重复点则取消     |
| TC-COM-04 | 热门话题显示  | 帖子互动数高时是否上热门区 | 热门区出现帖子             |
| TC-COM-05 | 内容审核机制  | 敏感词是否被拦截/提示      | 给出“内容不合规”提示       |
| TC-COM-06 | 标签推荐      | 选择话题是否推荐相关内容   | 推荐结果合理、及时加载     |
| TC-COM-07 | 关注/取关系统 | 关注后是否成功建立关注关系 | 动态展示更新               |



#### ✅ 3. **Schedule（日程与任务模块）**

| 用例编号  | 用例名称             | 测试点                     | 预期结果                  |
| --------- | -------------------- | -------------------------- | ------------------------- |
| TC-SCH-01 | 添加任务清单         | 是否可设置日期/优先级      | 列表显示任务 + 状态可勾选 |
| TC-SCH-02 | 事件提醒触发         | 设置提醒是否能按时通知     | 到时弹出提醒/响铃提示     |
| TC-SCH-03 | 日/周/月视图切换     | 是否能无误切换不同日历视图 | 各视图正常显示            |
| TC-SCH-04 | 删除任务是否更新视图 | 删除后是否同步更新         | 日历图/列表同步清除       |



#### ✅ 4. **LifeServing（生活服务）模块**

| 用例编号 | 用例名称         | 测试点                             | 预期结果                     |
| -------- | ---------------- | ---------------------------------- | ---------------------------- |
| TC-LS-01 | 发布内容管理     | 发布好物推荐/活动等信息            | 内容展示无误                 |
| TC-LS-02 | 辅助器具推荐     | 推荐列表是否分类清晰/加载正确      | 分类显示 + 图片正常          |
| TC-LS-03 | 学习设备推荐     | 展示硬件学习工具列表               | 内容图文加载完整             |
| TC-LS-04 | 就业信息推送     | 职位内容、公司信息展示是否完整     | 包含岗位名称、描述、联系方式 |
| TC-LS-05 | 残障友好企业标识 | 是否加V / 标签区分                 | 有“友好企业”提示             |
| TC-LS-06 | 无障碍路线规划   | 是否能绘制无台阶/电梯路线          | 地图路径合理                 |
| TC-LS-07 | 实时公交提醒     | 路线是否加载正确/更新是否及时      | 实时展示公交进站时间         |
| TC-LS-08 | 活动预告展示     | 亲子/文娱/演出分类信息加载是否完整 | 可报名 + 有时间地点说明      |



#### ✅ 5. **MyPage（个人中心）模块**

| 用例编号 | 用例名称           | 测试点                          | 预期结果                     |
| -------- | ------------------ | ------------------------------- | ---------------------------- |
| TC-MY-01 | 修改头像           | 上传头像 + 预览功能是否生效     | 显示新头像                   |
| TC-MY-02 | 修改资料           | 昵称/简介/联系方式可修改        | 保存后页面同步更新           |
| TC-MY-03 | 收藏管理           | 收藏帖子/课程后是否能查看       | 我的收藏页显示内容           |
| TC-MY-04 | 账号注册/登录/登出 | 是否可注册新用户 + 正确跳转状态 | 新用户进入首页，旧账号可退出 |
| TC-MY-05 | 权限角色识别       | 是否区分普通用户/审核员角色     | 页面显示不同选项             |



#### ✅ 6. **技术实现相关（稳定性/架构）测试**

| 用例编号   | 用例名称              | 测试点                        | 预期结果                 |
| ---------- | --------------------- | ----------------------------- | ------------------------ |
| TC-TECH-01 | SQLite 数据读写测试   | 批量操作课程/帖子是否存取正常 | 数据不丢失，响应时间正常 |
| TC-TECH-02 | MediaPipe模型崩溃恢复 | 强行关闭摄像头后是否重连      | 显示重连提示/自动恢复    |
| TC-TECH-03 | Tailwind 前端样式响应 | 各分辨率下页面是否响应式变化  | 不溢出，元素自适应       |





### 🏎️ 游戏控制模块

| 用例编号   | 模块     | 用例名称         | 前置条件                 | 测试步骤                         | 预期结果                           | 优先级 |
| ---------- | -------- | ---------------- | ------------------------ | -------------------------------- | ---------------------------------- | ------ |
| TC-GAME-01 | 游戏控制 | 加速动作识别     | 摄像头运行正常，程序启动 | 举起右手拇指上扬                 | 车辆开始加速                       | 高     |
| TC-GAME-02 | 游戏控制 | 刹车动作识别     | 同上                     | 举起左手拇指上扬                 | 车辆开始减速                       | 高     |
| TC-GAME-03 | 游戏控制 | 左右转向动作识别 | 同上                     | 向左倾手掌                       | 车辆向左转弯                       | 高     |
| TC-GAME-04 | 游戏控制 | 手势连续识别切换 | 程序运行中               | 快速从加速 → 左转 → 刹车切换手势 | 每步操作都有反馈，游戏响应流畅     | 高     |
| TC-GAME-05 | 游戏控制 | 识别抖动干扰测试 | 程序运行中，抖动手指     | 快速小幅度摆动手指               | 系统不误触操作，保持稳定           | 中     |
| TC-GAME-06 | 游戏控制 | 虚拟手柄断连恢复 | 手柄模拟开启中           | 断开 vgamepad 端口 → 重连        | 程序检测中断并尝试自动恢复         | 中     |
| TC-GAME-07 | 游戏控制 | 低帧率下性能表现 | 模拟20fps摄像头          | 尝试完成左右转、加速等动作       | 出现识别滞后，界面给出低帧警告     | 中     |
| TC-GAME-08 | 游戏控制 | UI反馈准确性     | 摄像头运行中             | 做出加速动作，观察 UI 面板反馈   | 显示“当前动作：加速”，图像区域标亮 | 中     |



## 四、测试程序实现与技术支撑

本项目测试除使用主系统 UI 操作外，亦开发了两套独立测试程序用于识别稳定性、输入准确性与边界场景的验证，覆盖核心逻辑路径，支撑高频回归测试与离线分析。

### 4.1 手势识别测试程序（wavecontrol-test 模块）

项目测试脚本集中存放于 `wavecontrol-test/src/` （gesture分支）路径下，采用 TypeScript + Vue3 框架实现，通过 MediaPipe 实时检测与手势逻辑模块协同，实现系统功能验证。

#### 4.1.1 hand_landmark 模块

- **detector.ts**
   核心手部关键点检测模块，封装对 MediaPipe 的调用逻辑，统一输出手部21个关键点的坐标、置信度等数据。
  - 功能点：初始化摄像头流、绑定回调、封装模型参数。
  - 用于：为 `VideoDetector.vue` 和 `gesture_handler.ts` 提供关键点数据源。
- **gesture_handler.ts**
   手势解析与事件派发模块，将 landmark 数据解析为具体手势动作（如光标控制、点击、跳跃等）。
  - 支持自定义手势库扩展。
  - 与游戏控制模块或系统控制指令绑定。
- **VideoDetector.vue**
   Vue 组件封装，展示摄像头实时画面 + 可视化 landmark 点位（调试模式用）。
  - 提供测试 UI 面板，便于调试每个手势识别过程。
  - 集成 FPS 状态、实时识别手势结果反馈。

#### 4.1.2 独立运行说明与调试提示

- **模块定位：**
   `wavecontrol-test` 为独立测试工程，当前未集成至主项目的 UI 页面路由体系，主要用于**手势识别逻辑的单元测试与调试验证**。
- **运行状态说明：**
   启动后页面加载为空白（白屏），属**正常表现**，原因如下：
  - 项目尚未渲染任何主界面组件；
  - 测试逻辑运行主要依赖控制台输出来验证关键逻辑（如 landmark 检测、手势判断等）。
- **调试建议：**
   启动后打开浏览器开发者工具（快捷键 `F12` 或 `Ctrl+Shift+I`），查看：
  - 控制台（Console）：打印识别结果、错误日志、手势状态；
  - 网络（Network）：确认模型文件是否成功加载；
  - 元素（Elements）：手动挂载 `VideoDetector.vue`注入测试组件进行临时渲染调试。



### 4.2 游戏控制模块测试（`test.py` 等）

### 4.2.1 模块定位与结构

该模块为游戏控制核心动作识别的测试环境，主要用于模拟真实场景下用户的手势输入，评估系统能否准确识别特定动作（如加速、转弯、刹车等），并通过 OpenCV 实时可视化手势状态与角度变化。

- **所在目录：** `wavecontrol/test_py/`（`game_control` 分支）
- **相关脚本：**
  - `test.py`：主测试入口，执行实时手势识别与状态展示。
  - `gesture_detector.py`：封装具体的手势识别逻辑。
  - `utils.py`：通用工具类，如角度计算、数据格式处理等。
  - `test_xbox.py`：拟用于连接虚拟 Xbox 控制器，模拟游戏输入。
  - `test_gui.py`：图形界面测试入口。



### 4.2.2 核心测试逻辑（基于 `test.py`）

**功能点解析：**

- **手势状态追踪：**
   通过 `gesture_status` 字典记录五类状态：
  - `Left Fist`、`Right Fist`：用于映射刹车/加速等动作
  - `Left Thumb`、`Right Thumb`：映射转向或音量等功能
  - `Angle`：表示当前手势的偏转角度，用于模拟方向盘行为或特殊动作
- **视觉反馈：**
   使用 `OpenCV` (`cv2`) 实时将识别结果叠加在摄像头图像上，显示五种状态的当前值，方便快速人工验证是否识别准确。
- **模块化调用：**
   `GestureDetector` 实例通过 `gesture_detector.py` 导入，使得识别逻辑可独立测试、方便集成到主游戏模块。

------

#### 4.2.3 使用说明

- **启动方法：**

  ```
  python test.py
  ```

  **运行效果：**

  - 打开摄像头窗口；
  - 实时显示识别到的五项手势状态；
  - 开发者可通过手部动作验证识别准确性。

- **测试目标：**

  - 验证关键手势在自然使用状态下的识别准确率；
  - 评估系统在不同光照/距离/角度条件下对“加速”“刹车”“左右转”的响应稳定性；
  - 检查 OpenCV 图像反馈是否与真实操作一致，便于回归对比。



## 五、测试结果分析

#### 项目整体手动测试结果：

[⌛️项目测试结果](./项目测试结果.xlsx)

#### 主平台自动化测试结果： 

全部测试通过，覆盖率达79%

![主平台自动化测试结果](./img/主平台自动化测试结果.png)

#### WaveSign平台自动化测试结果：

全部测试通过，覆盖率达93%

具体测试设计和结果见以下链接：

[WaveSign测试文档](https://gitee.com/wydhhh/software-engineering/blob/wavesign/WaveSign%E6%B5%8B%E8%AF%95%E6%96%87%E6%A1%A3.md)

[WaveSign测试结果html报告](https://gitee.com/wydhhh/software-engineering/tree/wavesign/htmlcov)



### **5.1 测试通过率**

- **总体通过率：**
   在所有模块（主控制系统 + WaveSign + 游戏控制模块）共计 **50+ 条用例 × 10次测试 = 500+ 次执行记录**中，约 **88%** 的测试结果为“通过”，**12%** 的测试记录显示“未通过”。
- **通过率较高的模块：**
  - **主控制系统：**通过率 **>90%**，大部分基础手势（如光标控制、鼠标点击、滚动控制）表现稳定。
  - **WaveSign 社区与个人中心模块：**通过率 **约95%**，发帖、评论、关注、资料修改等常规操作无明显问题。
- **通过率较低的模块：**
  - **WaveSign SLClassroom（手语教室）：**实时识别和视频上传评分测试中偶尔出现 **识别延迟** 或 **评分不稳定**，通过率约 **80%**。
  - **游戏控制模块：**“低帧率下性能表现”与“识别抖动干扰测试”未通过率稍高（**20% 左右**），主要原因是低帧率摄像头模拟下识别滞后明显。

------

### **5.2 典型问题分析**

- **（1）识别类问题：**
  - 当背景复杂或光照不足时，MediaPipe 模型识别准确率下降，个别测试记录显示 **响应时间超过0.7s**，甚至未正确识别手势。
  - “六指手势启动语音识别”在部分测试中未触发，需要优化手势阈值。
- **（2）性能问题：**
  - 游戏模块在模拟 **20fps 低帧率**摄像头时，出现识别滞后，UI延迟反馈。
  - 部分 UI 动画在高分辨率（4K）设备上存在轻微卡顿，需要进一步优化前端渲染。
- **（3）社区系统：**
  - 敏感词拦截逻辑偶尔误报，如普通词语被识别为敏感词。
- **（4）任务提醒功能：**
  - **日/周/月视图切换**测试中发现，在多任务快速切换时，少数场景下界面刷新不完全。

------

### **5.3 综合结论**

- WaveControl 系统整体功能 **满足预期目标**，大部分核心功能已稳定实现。



