WaveControl/项目测试文档.md

📋 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 图像反馈是否与真实操作一致，便于回归对比。

五、测试结果分析

项目整体手动测试结果：

⌛️项目测试结果

主平台自动化测试结果：

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

WaveSign平台自动化测试结果：

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

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

WaveSign测试文档

WaveSign测试结果html报告

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 系统整体功能 满足预期目标，大部分核心功能已稳定实现。