mi-task/single_test/README.md

# 机器狗子运动函数测试套件

这个测试套件提供了对机器狗各种运动功能的独立测试，方便您在实体机器狗上测试和验证各个子运动函数的效果。

## 📁 文件结构

```
single-test/
├── README.md                    # 说明文档
├── test_main.py                 # 主测试脚本（菜单入口）
├── test_basic_movements.py      # 基础运动测试
├── test_arc_movements.py        # 弧形运动测试  
├── test_custom_gait.py         # 自定义步态测试
├── test_vision_functions.py    # 视觉功能测试
└── test_complex_movements.py   # 复杂运动测试
```

## 🚀 快速开始

### 方法1：使用主菜单（推荐）

```python
# 在您的主控制脚本中添加：
from single_test.test_main import main_menu

# 初始化控制器和消息对象后
main_menu(ctrl, msg)
```

### 方法2：运行特定测试套件

```python
# 运行基础运动测试
from single_test.test_basic_movements import run_basic_movement_tests
run_basic_movement_tests(ctrl, msg)

# 运行弧形运动测试
from single_test.test_arc_movements import run_arc_movement_tests
run_arc_movement_tests(ctrl, msg)
```

### 方法3：交互式测试模式（快速测试）

```python
# 启动交互式测试模式
from single_test.test_main import run_interactive_test_selection
run_interactive_test_selection(ctrl, msg)
```

这种模式提供快速命令行界面，支持：
- 快速输入测试编号（如 `11` 表示原地旋转90度）
- 快捷命令（`h` 帮助、`s` 状态、`c` 清屏、`q` 退出）
- 实时状态查看和帮助信息

### 方法4：运行单个测试函数

```python
# 测试原地旋转90度
from single_test.test_basic_movements import test_turn_90_degrees
test_turn_90_degrees(ctrl, msg)

# 测试俯身步态
from single_test.test_custom_gait import test_stoop_gait
test_stoop_gait(ctrl, msg)
```

## 📋 测试模块详解

### 1. 基础运动测试 (`test_basic_movements.py`)

测试机器狗的基本运动能力：

- **原地旋转测试**
  - `test_turn_90_degrees()` - 原地旋转90度
  - `test_turn_180_degrees()` - 原地旋转180度

- **直线移动测试**
  - `test_go_straight_1m()` - 直线前进1米
  - `test_go_straight_backward_1m()` - 直线后退1米

- **侧向移动测试**
  - `test_lateral_movement()` - 左右侧向移动

- **组合运动测试**
  - `test_square_movement()` - 正方形移动路径

### 2. 弧形运动测试 (`test_arc_movements.py`)

测试机器狗的弧形转弯和绕行能力：

- **弧形转弯测试**
  - `test_arc_turn_90_degrees()` - 90度弧形转弯
  - `test_arc_turn_180_degrees()` - 180度弧形转弯
  - `test_arc_turn_right_90_degrees()` - 右转90度弧形转弯

- **复杂弧形运动**
  - `test_s_curve_movement()` - S形弯道运动
  - `test_different_radius_turns()` - 不同半径弧形转弯测试

### 3. 自定义步态测试 (`test_custom_gait.py`)

测试机器狗的特殊步态和姿态：

- **基础步态**
  - `test_normal_walking_gait()` - 正常行走步态
  - `test_stone_road_gait()` - 石板路步态（快步跑）

- **特殊步态**
  - `test_stoop_gait()` - 俯身步态（通过低矮障碍）
  - `test_climbing_gait()` - 爬坡步态（上坡运动）

- **姿态控制**
  - `test_lie_down_stand_up()` - 躺下和站起动作

### 4. 视觉功能测试 (`test_vision_functions.py`)

测试机器狗的视觉识别和分析能力：

- **目标识别**
  - `test_qr_code_scanning()` - QR码扫描功能
  - `test_arrow_detection()` - 箭头检测功能

- **环境分析**
  - `test_horizontal_line_detection()` - 横线检测功能
  - `test_sky_analysis()` - 天空区域分析
  - `test_yellow_area_analysis()` - 黄色区域分析

- **运动中视觉**
  - `test_movement_with_qr_scanning()` - 移动过程中的QR码扫描

### 5. 复杂运动测试 (`test_complex_movements.py`)

测试机器狗的高级运动组合：

- **复杂轨迹**
  - `test_continuous_curves()` - 连续弯道运动（模拟任务2）
  - `test_figure_eight_movement()` - 8字形运动
  - `test_spiral_movement()` - 螺旋运动

- **精确控制**
  - `test_precision_positioning()` - 精确定位测试
  - `test_dual_track_following()` - 双轨道跟随

- **组合运动**
  - `test_combined_movements()` - 多动作组合测试

## 🎮 菜单系统

主测试脚本提供了友好的菜单界面：

```
============================================================
           机器狗子运动函数测试套件
============================================================
🎯 测试套件:
  1. 基础运动测试      - 旋转、直线移动、侧向移动
  2. 弧形运动测试      - 弧形转弯、S形弯道
  3. 自定义步态测试    - 俯身、爬坡、石板路步态
  4. 视觉功能测试      - QR码、箭头、横线检测
  5. 复杂运动测试      - 连续弯道、8字形、螺旋运动

🔧 测试选项:
  6. 运行所有测试      - 执行完整测试流程
  7. 单个测试选择      - 菜单式选择单个测试
  8. 交互式测试模式    - 快速命令行测试
  0. 退出
============================================================
💡 提示: 建议先从基础运动测试开始，确保机器狗处于安全位置
```

### 三种测试模式

1. **测试套件模式**：选择1-5，运行完整的测试套件
2. **单个测试选择**：选择7，进入详细的单个测试菜单
3. **交互式测试模式**：选择8，快速命令行测试界面

### 交互式测试模式特性

- **快速测试**：直接输入两位数编号（如`11`、`34`）
- **实时状态**：输入`s`查看机器狗当前状态
- **帮助信息**：输入`h`获取详细帮助
- **清屏功能**：输入`c`清理屏幕
- **快速退出**：输入`q`退出测试模式

## 📊 测试输出

每个测试都会提供详细的输出信息：

- **位置信息**：起始位置、最终位置、移动距离
- **角度信息**：起始角度、最终角度、角度变化
- **性能指标**：移动精度、执行时间、成功率
- **错误诊断**：失败原因、异常信息

## ⚙️ 配置说明

### 观察模式
大部分测试函数都支持 `observe` 参数：
```python
test_turn_90_degrees(ctrl, msg, observe=True)  # 输出详细信息
test_turn_90_degrees(ctrl, msg, observe=False) # 静默执行
```

### 自定义参数
某些测试支持自定义参数：
```python
# 自定义速度和距离
go_straight(ctrl, msg, distance=2.0, speed=0.3, observe=True)

# 自定义转弯半径
arc_turn_around_hori_line(ctrl, msg, angle_deg=90, radius=0.5)
```

## 🔧 故障排除

### 常见问题

1. **导入错误**
   ```
   ModuleNotFoundError: No module named 'xxx'
   ```
   - 确保路径设置正确
   - 检查父目录是否包含所需模块

2. **控制器未初始化**
   ```
   AttributeError: 'NoneType' object has no attribute 'xxx'
   ```
   - 确保 `ctrl` 和 `msg` 对象已正确初始化
   - 检查机器狗连接状态

3. **步态文件缺失**
   ```
   FileNotFoundError: [Errno 2] No such file or directory: 'xxx.toml'
   ```
   - 确保步态配置文件存在于正确路径
   - 检查 task_3 和 task_4 目录中的 .toml 文件

### 调试建议

1. **单步测试**：先运行简单的基础运动测试
2. **观察模式**：启用 `observe=True` 查看详细输出
3. **逐步验证**：按顺序测试各个功能模块
4. **日志检查**：查看日志输出了解执行状态

## 📝 使用示例

### 例子1：测试原地旋转效果
```python
from single_test.test_basic_movements import test_turn_90_degrees

# 测试原地旋转90度
test_turn_90_degrees(ctrl, msg, observe=True)
```

### 例子2：测试俯身步态
```python
from single_test.test_custom_gait import test_stoop_gait

# 测试俯身步态
test_stoop_gait(ctrl, msg, observe=True)
```

### 例子3：运行完整测试套件
```python
from single_test.test_main import main_menu

# 启动菜单系统
main_menu(ctrl, msg)
```

## 🛡️ 安全提示

1. **测试环境**：确保在安全的测试环境中运行
2. **空间要求**：某些测试需要较大的活动空间
3. **监督运行**：建议在有人监督的情况下运行测试
4. **紧急停止**：了解如何紧急停止机器狗运动

## 📞 支持

如果您在使用过程中遇到问题，请：

1. 检查本文档的故障排除部分
2. 查看代码注释了解函数参数
3. 确认机器狗硬件和软件状态正常
4. 验证所有依赖模块是否正确安装

---

**注意**：此测试套件基于原始任务1-5的代码提取和整理，确保与您的机器狗控制系统兼容。