@xiaolaa2/ableton-copilot-mcp/test-plan.md

Ableton Live MCP depend on Ableton JS

# MCP Ableton Tools 全面测试计划

## 1. 测试目标

- 验证所有 MCP Ableton tools 的功能正确性
- 测试正常使用场景和各种异常情况的处理能力
- 确保工具间的交互正常
- 详细记录测试结果，包括问题和解决方案

## 2. 测试环境准备

- Ableton Live 版本: 11或12 (记录具体版本)
- 操作系统: Windows 10/11
- 确保测试前有足够的素材:
  - 音频样本文件
  - MIDI片段
  - 第三方插件

## 3. 测试框架

每个工具测试将包括:
1. **基本功能测试** - 验证工具在正常参数下的基本功能
2. **边界值测试** - 测试参数的边界条件
3. **异常处理测试** - 测试错误参数和异常情况
4. **性能测试** - 测试在大量数据或频繁调用下的性能
5. **交互测试** - 测试与其他工具的交互

## 4. 测试范围

### 4.1 Browser Tools (浏览器工具)

#### 4.1.1 列出资源 (list_resources)
- **正常场景**:
  - 列出所有音频效果器
  - 列出所有乐器
  - 列出所有插件
  - 列出所有样本
  - 列出所有鼓机
  - 列出所有MIDI效果器
  - 列出所有声音
- **异常场景**:
  - 在Ableton未启动时调用
  - 提供无效的资源类型参数

#### 4.1.2 加载设备 (load_device)
- **正常场景**:
  - 加载音频效果器到当前选中轨道
  - 加载乐器到指定MIDI轨道
  - 加载插件到指定轨道
- **异常场景**:
  - 提供不存在的设备ID
  - 提供不存在的轨道ID
  - 加载音频效果器到无效轨道
  - 加载过大插件时的性能

### 4.2 Song Tools (歌曲工具)

#### 4.2.1 获取歌曲属性 (get_song_properties)
- **正常场景**:
  - 获取歌曲基本信息(名称、速度、音阶等)
  - 获取轨道列表
  - 获取场景列表
- **异常场景**:
  - 在Ableton未启动时调用
  - 请求不支持的属性

#### 4.2.2 获取歌曲视图属性 (get_song_view_properties)
- **正常场景**:
  - 获取当前选中片段
  - 获取当前选中轨道
  - 获取当前选中场景
- **异常场景**:
  - 无选中内容时调用
  - 请求不支持的属性

#### 4.2.3 设置歌曲属性 (set_song_property)
- **正常场景**:
  - 修改歌曲速度
  - 启用/禁用循环
  - 设置循环起始和结束位置
- **异常场景**:
  - 设置无效的速度值(负数或过大值)
  - 设置无效的循环位置(结束早于开始)

#### 4.2.4 设置歌曲视图属性 (set_song_view_property)
- **正常场景**:
  - 选择特定片段
  - 选择特定轨道
  - 选择特定场景
- **异常场景**:
  - 选择不存在的片段
  - 选择不存在的轨道
  - 选择不存在的场景

#### 4.2.5 创建轨道 (create_track)
- **正常场景**:
  - 创建MIDI轨道(不同索引位置)
  - 创建音频轨道(不同索引位置)
  - 创建返送轨道
- **异常场景**:
  - 使用无效的轨道类型
  - 使用无效的索引位置(负数、超大数值)
  - 在保护状态下创建轨道

#### 4.2.6 删除轨道 (delete_track)
- **正常场景**:
  - 删除MIDI轨道
  - 删除音频轨道
  - 删除返送轨道
- **异常场景**:
  - 删除不存在的轨道索引
  - 删除主轨道
  - 删除已被锁定的轨道

#### 4.2.7 复制轨道 (duplicate_track)
- **正常场景**:
  - 复制MIDI轨道(含设备和片段)
  - 复制音频轨道(含设备和片段)
- **异常场景**:
  - 复制不存在的轨道索引
  - 复制返送轨道(不支持)
  - 复制主轨道(不支持)

#### 4.2.8 时间范围录音 (record_by_time_range)
- **正常场景**:
  - 录制4小节音频
  - 录制精确时间范围(非整数拍)
- **异常场景**:
  - 轨道未设置为录音状态
  - 未设置正确的输入路由
  - 结束时间早于开始时间
  - 录音期间项目状态改变

### 4.3 Clip Tools (片段工具)

#### 4.3.1 获取片段属性 (get_clip_properties)
- **正常场景**:
  - 获取MIDI片段属性
  - 获取音频片段属性
  - 获取所有可用属性
  - 获取特定属性子集
- **异常场景**:
  - 获取不存在的片段
  - 请求不支持的属性
  - 音频片段特有属性应用于MIDI片段

#### 4.3.2 删除片段音符 (remove_clip_notes)
- **正常场景**:
  - 删除特定音高范围的音符
  - 删除特定时间范围的音符
  - 删除所有音符
- **异常场景**:
  - 在音频片段上操作
  - 使用无效的音高范围
  - 使用无效的时间范围
  - 在空片段上操作

#### 4.3.3 添加音符到片段 (add_notes_to_clip)
- **正常场景**:
  - 添加单个音符
  - 添加多个按和弦排列的音符
  - 添加多个按顺序排列的音符
- **异常场景**:
  - 添加无效音符(无效音高、负时长)
  - 在音频片段上操作
  - 添加超出片段长度的音符

#### 4.3.4 替换片段所有音符 (replace_all_notes_to_clip)
- **正常场景**:
  - 用单个音符替换
  - 用和弦序列替换
  - 用旋律替换
- **异常场景**:
  - 用无效音符替换
  - 在音频片段上操作
  - 替换后长度超出片段长度

#### 4.3.5 设置片段属性 (set_clips_property)
- **正常场景**:
  - 设置MIDI片段名称和颜色
  - 设置音频片段循环点
  - 设置多个片段属性
- **异常场景**:
  - 设置不存在的片段
  - 设置无效的属性值
  - 设置MIDI特有属性到音频片段

#### 4.3.6 裁剪片段 (crop_clip)
- **正常场景**:
  - 裁剪循环MIDI片段
  - 裁剪非循环MIDI片段
  - 裁剪音频片段
- **异常场景**:
  - 裁剪不存在的片段
  - 裁剪未设置适当标记的片段

#### 4.3.7 复制片段循环 (duplicate_clip_loop)
- **正常场景**:
  - 复制MIDI片段循环
  - 复制音频片段循环
- **异常场景**:
  - 复制不存在的片段
  - 复制未循环的片段
  - 复制无法循环的音频片段

#### 4.3.8 复制片段区域 (duplicate_clip_region)
- **正常场景**:
  - 复制MIDI片段区域(所有音高)
  - 复制MIDI片段区域(特定音高)
  - 使用不同移调复制
- **异常场景**:
  - 复制音频片段区域(不支持)
  - 使用无效的区域范围
  - 使用无效的移调量

### 4.4 Track Tools (轨道工具)

#### 4.4.1 获取轨道属性 (get_track_properties)
- **正常场景**:
  - 获取MIDI轨道属性
  - 获取音频轨道属性
  - 获取返送轨道属性
  - 获取主轨道属性
- **异常场景**:
  - 获取不存在的轨道
  - 请求不支持的属性

#### 4.4.2 创建空MIDI片段 (create_empty_midi_clip)
- **正常场景**:
  - 在MIDI轨道创建空片段
  - 创建不同长度的片段
  - 在不同时间位置创建
- **异常场景**:
  - 在音频轨道上创建
  - 使用无效长度(负数或零)
  - 使用无效时间位置

#### 4.4.3 设置轨道属性 (set_tracks_property)
- **正常场景**:
  - 设置轨道名称和颜色
  - 设置音量和声像
  - 设置多个轨道属性
- **异常场景**:
  - 设置不存在的轨道
  - 设置无效的属性值
  - 设置音频特有属性到MIDI轨道

#### 4.4.4 复制片段到轨道 (duplicate_clip_to_track)
- **正常场景**:
  - 复制MIDI片段到MIDI轨道
  - 复制音频片段到音频轨道
- **异常场景**:
  - 复制不存在的片段
  - 复制到不存在的轨道
  - 复制MIDI片段到音频轨道
  - 复制音频片段到MIDI轨道

#### 4.4.5 删除设备 (delete_device)
- **正常场景**:
  - 删除音频效果器
  - 删除乐器
  - 删除第三方插件
- **异常场景**:
  - 删除不存在的设备
  - 删除不存在的索引
  - 删除已锁定的设备

#### 4.4.6 创建音频片段 (create_audio_clip)
- **正常场景**:
  - 创建WAV格式音频片段
  - 创建MP3格式音频片段
  - 创建AIFF格式音频片段
- **异常场景**:
  - 创建在MIDI轨道上
  - 使用不存在的音频文件
  - 使用不支持的文件格式
  - 在已冻结的轨道上创建

### 4.5 Device Tools (设备工具)

#### 4.5.1 获取设备属性 (get_device_properties)
- **正常场景**:
  - 获取内置效果器属性
  - 获取内置乐器属性
  - 获取第三方插件属性
- **异常场景**:
  - 获取不存在的设备
  - 请求不支持的属性

#### 4.5.2 修改设备参数值 (modify_device_parameter_value)
- **正常场景**:
  - 修改常见参数(音量、频率等)
  - 修改布尔参数(开关状态)
  - 修改枚举参数(模式选择)
- **异常场景**:
  - 修改不存在的参数
  - 修改只读参数
  - 使用无效的参数值(超出范围)
  - 修改第三方插件参数(不确定支持)

### 4.6 History Tools (历史工具)

#### 4.6.1 获取操作历史 (get_operation_histories)
- **正常场景**:
  - 获取第一页历史
  - 使用不同页码和大小
- **异常场景**:
  - 使用无效的页码(负数)
  - 使用无效的页大小(过大、零)
  - 在没有历史记录时获取

#### 4.6.2 获取快照 (get_snapshot_by_history_id)
- **正常场景**:
  - 获取MIDI操作快照
  - 获取最近操作快照
  - 获取较旧操作快照
- **异常场景**:
  - 获取不存在的历史ID
  - 获取无快照的操作

#### 4.6.3 回滚操作 (rollback_by_history_id)
- **正常场景**:
  - 回滚添加音符操作
  - 回滚删除音符操作
  - 回滚替换音符操作
- **异常场景**:
  - 回滚不存在的历史ID
  - 回滚不支持的操作类型
  - 回滚已被依赖的操作

## 5. 测试结果记录模板

对每个测试用例记录:

```
测试工具: [工具名称]
测试场景: [场景描述]
测试时间: YYYY-MM-DD HH:MM
测试数据: [输入参数]
预期结果: [预期结果]
实际结果: [实际结果]
测试状态: [成功/失败/部分成功]
问题描述: [如果失败，详细描述问题]
解决方案: [解决思路或具体修复]
备注: [其他重要信息]
```

## 6. 测试实施计划

1. **准备阶段** (2天)
   - 准备测试环境和测试数据
   - 创建详细测试用例
   - 设置测试记录系统

2. **初步测试** (3天)
   - 完成所有正常场景的基本功能测试
   - 记录初步测试结果
   - 解决关键问题

3. **深入测试** (5天)
   - 完成所有异常场景测试
   - 进行边界值测试
   - 进行交互测试

4. **性能/稳定性测试** (2天)
   - 进行长时间连续操作测试
   - 进行高负载测试
   - 进行恢复能力测试

5. **回归测试** (2天)
   - 验证已修复的问题
   - 确保无新问题引入

6. **文档和报告** (1天)
   - 整理测试结果
   - 生成测试报告
   - 提出改进建议

## 7. 测试工具和自动化

1. **手动测试工具**
   - Ableton Live测试项目
   - 测试数据集(MIDI文件、音频文件等)
   - 测试记录模板

2. **自动化测试**
   - 编写简单的API测试脚本
   - 创建参数生成器用于边界测试
   - 设置基本的回归测试脚本

## 8. 已知限制和注意事项

1. 某些操作可能在Ableton Live不同版本之间有差异
2. 第三方插件可能会有兼容性问题
3. 大型项目中性能可能会下降
4. 某些文件格式可能不被所有版本支持
5. 需要确保测试不影响生产环境
6. 自动化测试可能无法覆盖所有用户界面交互
7. 某些回滚操作可能影响项目状态

## 9. 风险评估

| 风险 | 可能性 | 影响 | 缓解策略 |
|------|--------|------|----------|
| 版本兼容性问题 | 中 | 高 | 在多个版本上测试 |
| 第三方插件崩溃 | 高 | 中 | 隔离测试第三方插件 |
| 数据丢失 | 低 | 极高 | 始终使用测试项目复制品 |
| 自动化测试不完整 | 中 | 中 | 关键功能手动测试 |
| 测试资源不足 | 中 | 高 | 优先测试核心功能 |

## 10. 成功标准

1. 所有核心功能在正常情况下100%通过测试
2. 所有工具对异常输入有适当错误处理
3. 没有数据丢失或损坏的风险
4. 性能满足预期要求
5. 与Ableton Live的集成稳定可靠
6. 所有关键问题都有解决方案

## 11. 后续步骤

1. 根据测试结果更新文档
2. 创建用户指南和示例
3. 开发更多自动化测试
4. 优化性能和稳定性
5. 计划下一轮功能扩展和测试

## 12. 测试结果

### 12.1 Browser Tools（浏览器工具）测试结果

#### 列出资源 (list_resources)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:45
- **详细信息**：
  - 成功列出音频效果器，共49个内置效果器
  - 成功列出乐器，共23个内置乐器
  - 每个资源项包含ID、名称和加载状态
- **问题记录**：无

#### 加载设备 (load_device)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:49
- **详细信息**：
  - 成功将Auto Shift设备加载到MIDI轨道
  - 设备ID: id_644776000
  - 设备在轨道上正确显示
- **问题记录**：无

### 12.2 Song Tools（歌曲工具）测试结果

#### 获取歌曲属性 (get_song_properties)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:46
- **详细信息**：
  - 成功获取基本信息：根音符(C)、音阶(Major)、速度(120 BPM)等
  - 成功获取轨道列表
- **问题记录**：无

#### 创建轨道 (create_track)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:47
- **详细信息**：
  - 成功创建MIDI轨道，返回轨道ID: live_120089512
  - 成功创建音频轨道，返回轨道ID: live_618211376
- **问题记录**：无

#### 设置歌曲属性 (set_song_property)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:55
- **详细信息**：
  - 成功将歌曲速度从120 BPM修改为125 BPM
- **问题记录**：无

#### 复制轨道 (duplicate_track)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:50
- **详细信息**：
  - 成功复制索引0位置的音频轨道
  - 新轨道保留了原轨道的名称和颜色属性
- **问题记录**：无

### 12.3 Clip Tools（片段工具）测试结果

#### 获取片段属性 (get_clip_properties)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:51
- **详细信息**：
  - 成功获取MIDI片段的名称、颜色和音符
  - 成功获取片段的循环信息
- **问题记录**：无

#### 添加音符到片段 (add_notes_to_clip)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:50
- **详细信息**：
  - 成功添加4个音符到MIDI片段
  - 音符按预期被添加，形成C大调音阶
  - 操作被记录到历史记录中（ID: 1）
- **问题记录**：无

#### 设置片段属性 (set_clips_property)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:51
- **详细信息**：
  - 成功修改片段名称为"测试MIDI片段"
  - 成功修改片段颜色为红色
- **问题记录**：无

#### 复制片段循环 (duplicate_clip_loop)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:53
- **详细信息**：
  - 成功将循环长度从4拍扩展到8拍
  - 音符被正确复制到新区域
- **问题记录**：无

#### 复制片段区域 (duplicate_clip_region)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:54
- **详细信息**：
  - 成功将0-2拍的区域复制到第6拍位置
  - 应用了+7半音的移调，音符升高了一个五度
- **问题记录**：无

### 12.4 Track Tools（轨道工具）测试结果

#### 获取轨道属性 (get_track_properties)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:55
- **详细信息**：
  - 成功获取轨道的设备列表
  - 能够正确显示轨道上的设备状态
- **问题记录**：无

#### 创建空MIDI片段 (create_empty_midi_clip)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:47
- **详细信息**：
  - 成功在MIDI轨道上创建4拍长的空片段
  - 片段ID: live_619884912
- **问题记录**：无

#### 设置轨道属性 (set_tracks_property)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:49
- **详细信息**：
  - 成功修改轨道名称为"测试音频轨道"
  - 成功修改轨道颜色为红色
- **问题记录**：无

#### 复制片段到轨道 (duplicate_clip_to_track)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:52
- **详细信息**：
  - 成功将MIDI片段复制到另一个MIDI轨道
- **问题记录**：无

#### 删除设备 (delete_device)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:54
- **详细信息**：
  - 成功删除轨道上索引0位置的Auto Shift设备
- **问题记录**：无

### 12.5 Device Tools（设备工具）测试结果

#### 获取设备属性 (get_device_properties)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:53
- **详细信息**：
  - 成功获取Auto Shift设备的详细属性
  - 返回数据包含：
    - 类名：AutoShift
    - 激活状态：true
    - 设备参数列表（49个参数）
- **问题记录**：无

#### 修改设备参数值 (modify_device_parameter_value)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:53
- **详细信息**：
  - 成功修改Auto Shift的Shift Semitones参数值为7
  - 参数ID: live_123978864
- **问题记录**：无

### 12.6 History Tools（历史工具）测试结果

#### 获取操作历史 (get_operation_histories)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:52
- **详细信息**：
  - 成功获取最近的操作历史
  - 能够获取到添加音符操作的历史记录(ID:1)
- **问题记录**：无

#### 获取快照 (get_snapshot_by_history_id)
- **测试状态**：成功
- **测试时间**：2025-05-06 10:52
- **详细信息**：
  - 成功获取历史ID 1的快照
  - 快照包含操作前的状态信息
- **问题记录**：无