# GNS3 Copilot 手动测试指南

> 本文档提供 GNS3 Copilot 的完整手动测试流程，帮助确保项目功能的正确性和稳定性。

---

## 目录

- [一、环境准备测试](#一环境准备测试)
- [二、应用启动测试](#二应用启动测试)
- [三、Settings 页面测试](#三settings-页面测试)
- [四、Chat 页面测试](#四chat-页面测试)
- [五、工具功能测试](#五工具功能测试)
- [六、Help 页面测试](#六help-页面测试)
- [七、边界和异常测试](#七边界和异常测试)
- [八、持久化测试](#八持久化测试)
- [九、UI/UX 测试](#九uiux-测试)
- [十、测试报告模板](#十测试报告模板)

---

## 一、环境准备测试

### 1.1 环境依赖检查

| 检查项 | 操作命令 | 预期结果 |
|--------|----------|----------|
| Python 版本 | `python --version` | Python 3.10 或更高版本 |
| 虚拟环境 | `source venv/bin/activate` | 终端显示虚拟环境激活状态 |
| 依赖安装 | `pip install -e .` | 无错误，所有包成功安装 |
| 验证安装 | `gns3-copilot --help` | 显示帮助信息 |

### 1.2 GNS3 服务器检查

| 检查项 | 操作命令 | 预期结果 |
|--------|----------|----------|
| 服务运行状态 | 访问 `http://localhost:3080` | 显示 GNS3 Web 界面 |
| API 版本检查 | `curl http://localhost:3080/v2/version` | 返回 JSON 格式的版本信息 |
| 项目列表 | `curl http://localhost:3080/v2/projects` | 返回项目列表（可为空） |

### 1.3 环境变量检查

| 检查项 | 操作 | 预期结果 |
|--------|------|----------|
| .env 文件 | `ls -la | grep .env` | 项目根目录下存在 .env 文件 |
| 环境变量加载 | 检查应用日志 | 正确加载环境变量 |

---

## 二、应用启动测试

### 2.1 基本启动测试

**测试步骤：**
```bash
gns3-copilot
```

| 验证项 | 预期结果 |
|--------|----------|
| 浏览器自动打开 | 默认浏览器导航至 `http://localhost:8501` |
| 页面加载成功 | 显示 GNS3 Copilot 标题和侧边栏导航 |
| 无控制台错误 | 应用日志正常，无异常错误 |
| 应用响应 | 页面元素可点击，交互正常 |

### 2.2 自定义端口启动测试

**测试步骤：**
```bash
gns3-copilot --server.port 8080
```

| 验证项 | 预期结果 |
|--------|----------|
| 应用在指定端口 | 浏览器导航至 `http://localhost:8080` |
| 默认端口不冲突 | 8501 端口未被占用 |

### 2.3 网络访问启动测试

**测试步骤：**
```bash
gns3-copilot --server.address 0.0.0.0 --server.port 8080
```

| 验证项 | 预期结果 |
|--------|----------|
| 外部访问 | 同网络其他设备可访问 `http://<IP>:8080` |

---

## 三、Settings 页面测试

### 3.1 导航到 Settings 页面

| 操作步骤 | 预期结果 |
|----------|----------|
| 点击侧边栏 "Settings" 链接 | 页面切换到 Settings 页面 |
| 显示配置表单 | 所有配置项按类别分组显示 |

### 3.2 GNS3 服务器配置

#### 3.2.1 API v2 配置测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **正常配置 v2** | 选择 API Version: v2，填写 Host、URL | 保存成功，显示 "Configuration saved" |
| **不填写用户名密码** | API v2 下留空用户名密码 | 保存成功（v2 不需要认证） |
| **连接测试** | 点击 "Test Connection" 按钮 | 显示 "Connection successful" |

#### 3.2.2 API v3 配置测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **正常配置 v3** | 选择 API Version: v3，填写所有字段 | 保存成功 |
| **不填写认证信息** | API v3 下留空用户名密码 | 保存失败，提示需要认证信息 |
| **连接测试** | 填写正确的用户名密码并测试 | 显示连接成功或失败 |

#### 3.2.3 异常情况测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **无效 URL** | 填写 `http://invalid-host:9999` | 保存时提示连接错误 |
| **空 Host** | Host 字段留空 | 保存失败，提示必填 |
| **GNS3 服务未启动** | 填写正确 URL 但服务未运行 | 连接测试失败 |

### 3.3 LLM 模型配置

#### 3.3.1 OpenAI 配置测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **正常配置 OpenAI** | 选择 Provider: openai，填写 Model Name 和 API Key | 保存成功 |
| **使用 GPT 模型** | Model Name: gpt-4o-mini | 保存成功 |
| **无效 API Key** | 填写错误 Key，发送测试消息 | 模型调用失败，显示认证错误 |

#### 3.3.2 DeepSeek 配置测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **正常配置 DeepSeek** | 选择 Provider: deepseek，填写 API Key | 保存成功 |
| **使用 DeepSeek 模型** | Model Name: deepseek-chat | 保存成功 |
| **测试模型调用** | 发送测试消息 | AI 正常响应 |

#### 3.3.3 第三方平台测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **OpenRouter 配置** | 选择 openrouter，填写 Base URL 和 API Key | 保存成功 |
| **使用自定义模型** | Model Name: google/gemini-2.5-flash | 保存成功 |
| **xAI 配置** | 选择 xai，填写对应参数 | 保存成功 |

### 3.4 其他设置

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **Linux 凭据配置** | 填写 Linux Console Username 和 Password | 保存成功 |
| **Temperature 调整** | 拖动滑块调整 | 值在 0.0-1.0 之间变化 |
| **Voice 功能配置** | 设置 VOICE=true | 语音功能开启 |

### 3.5 配置持久化测试

| 操作步骤 | 预期结果 |
|----------|----------|
| 修改所有配置并保存 | 项目根目录下 .env 文件更新 |
| 重启应用 | 所有配置保持不变 |
| 删除 .env 文件 | 应用使用默认配置 |

---

## 四、Chat 页面测试

### 4.1 会话管理测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **新建会话** | 点击侧边栏 "New Session" 按钮 | 生成新的 thread_id，会话选择器显示为 "New Session" |
| **查看会话列表** | 查看侧边栏 Session History 下拉框 | 显示所有历史会话（包含标题和 thread_id） |
| **选择历史会话** | 从下拉框选择一个历史会话 | 页面显示该会话的历史消息 |
| **切换会话** | 选择另一个会话 | 成功切换到选中的会话 |
| **删除会话** | 点击 "Delete" 按钮 | 显示删除成功提示，会话从列表中移除 |

### 4.2 项目选择（无项目状态）

#### 4.2.1 项目列表显示测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **有打开的项目** | GNS3 中有打开的项目 | 页面显示 "Workspace Selection" 和项目卡片列表 |
| **无打开的项目** | GNS3 中无打开的项目 | 显示提示信息 "Please select an opened project..." |
| **多个项目** | GNS3 中有多个打开项目 | 显示所有项目的卡片 |

#### 4.2.2 项目卡片信息测试

| 检查项 | 预期结果 |
|--------|----------|
| 项目名称 | 显示项目名称 |
| 项目 ID | 显示项目 UUID |
| 设备数量 | 显示 Device_Number |
| 链接数量 | 显示 Link_Number |
| 状态 | 显示项目状态（opened/closed） |
| Select 按钮 | 显示 "Select" 按钮 |

#### 4.2.3 选择项目测试

| 操作步骤 | 预期结果 |
|----------|----------|
| 点击项目的 "Select" 按钮 | 进入聊天界面，侧边栏显示当前项目名称 |

### 4.3 基础聊天功能测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **发送文本消息** | 在输入框输入 "你好" 并回车 | 消息显示在聊天界面，AI 响应 |
| **流式响应** | 观察响应过程 | AI 响应逐步显示，不是一次性全部出现 |
| **工具调用展示** | AI 调用工具时 | 显示工具调用信息（工具名称、参数）和结果 |
| **多轮对话** | 连续发送多条相关消息 | 上下文保持，AI 能理解上下文 |
| **空输入** | 发送空格或空字符串 | 提示需要输入内容 |

### 4.4 会话标题生成测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **第一轮对话** | 发送第一条消息并获得回复 | 会话列表自动生成新标题 |
| **标题内容** | 查看生成的标题 | 标题与对话内容相关，长度不超过 40 字符 |
| **多轮对话** | 继续对话 | 标题不再变化 |
| **切换会话** | 切换到其他会话 | 各会话标题独立显示 |

### 4.5 切换/退出项目测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **显示当前项目** | 查看侧边栏 | 显示 "Current Project: **{项目名}**" |
| **切换项目** | 点击 "Switch Project / Exit" 按钮 | 返回项目选择界面 |
| **状态保持** | 切换后重新选择之前的项目 | 历史消息和上下文保持 |

### 4.6 消息历史渲染测试

| 检查项 | 预期结果 |
|--------|----------|
| 用户消息 | 显示在右侧，有用户图标 |
| AI 消息 | 显示在左侧，有机器人图标 |
| 工具调用 | 显示工具调用框，包含工具名、参数 |
| 工具响应 | 显示工具响应框，包含响应内容 |
| 流式消息 | 逐步更新，最后定格为完整内容 |

---

## 五、工具功能测试

### 5.1 拓扑信息查询测试

#### 5.1.1 GNS3TopologyTool 测试

| 测试场景 | 用户输入 | 预期结果 |
|----------|----------|----------|
| **查询完整拓扑** | "查看当前项目拓扑" | 显示完整的项目拓扑 JSON |
| **查询设备信息** | "列出所有设备" | 显示所有设备列表及其详细信息 |
| **查询链接信息** | "显示所有连接" | 显示所有链路列表及其详细信息 |
| **拓扑上下文** | 进行其他操作后再次查询 | 拓扑信息基于当前选择的项目 |

### 5.2 节点管理工具测试

#### 5.2.1 GNS3TemplateTool 测试

| 测试场景 | 用户输入 | 预期结果 |
|----------|----------|----------|
| **获取所有模板** | "获取可用节点模板" | 列出 GNS3 服务器上所有可用模板 |
| **按名称查询** | "查找 Cisco IOSv 模板" | 显示匹配的模板信息 |
| **按类型查询** | "查找所有路由器模板" | 显示所有路由器类型模板 |

#### 5.2.2 GNS3CreateNodeTool 测试

| 测试场景 | 用户输入 | 预期结果 |
|----------|----------|----------|
| **创建单个节点** | "创建一个名为 R1 的路由器" | 节点创建成功，返回节点信息 |
| **指定模板** | "使用 Cisco IOSv 模板创建路由器 R2" | 使用指定模板创建节点 |
| **创建多个节点** | "创建 3 个交换机" | 创建多个节点，返回所有节点信息 |
| **创建失败** | "创建不存在的设备" | 显示错误信息 |

#### 5.2.3 GNS3StartNodeTool 测试

| 测试场景 | 用户输入 | 预期结果 |
|----------|----------|----------|
| **启动单个节点** | "启动 R1" | 显示启动进度，节点成功启动 |
| **启动多个节点** | "启动所有路由器" | 显示批量启动进度 |
| **进度显示** | 观察启动过程 | 显示进度条和启动状态 |
| **启动失败** | "启动不存在的节点" | 显示错误信息 |

### 5.3 链接管理工具测试

#### 5.3.1 GNS3LinkTool 测试

| 测试场景 | 用户输入 | 预期结果 |
|----------|----------|----------|
| **创建单条链路** | "连接 R1 和 R2" | 链接创建成功，返回链接信息 |
| **指定端口** | "将 R1 的 g0/0 连接到 R2 的 g0/0" | 使用指定端口创建链接 |
| **创建多条链路** | "连接 R1-R2、R2-R3、R3-R1" | 创建多个链接 |
| **重复链接** | "再次连接 R1 和 R2" | 显示端口已占用或创建成功（不同端口） |

### 5.4 配置命令工具测试

#### 5.4.1 ExecuteMultipleDeviceConfigCommands 测试

| 测试场景 | 用户输入 | 预期结果 |
|----------|----------|----------|
| **单设备配置** | "在 R1 上配置 hostname Router1" | 配置命令执行成功 |
| **多设备配置** | "在所有路由器上配置 loopback 0" | 批量配置，返回所有设备结果 |
| **多条命令** | 在 R1 上配置 hostname、banner motd 等 | 多条命令依次执行 |
| **复杂配置** | "配置 OSPF 区域 0" | 多条配置命令正确执行 |

#### 5.4.2 配置命令格式测试

| 测试场景 | 输入格式 | 预期结果 |
|----------|----------|----------|
| **JSON 格式** | 有效的 JSON 配置数组 | 正确解析并执行 |
| **列表格式** | Python 列表格式 | 正确解析并执行 |
| **格式错误** | 无效的 JSON 格式 | 显示格式错误提示 |

### 5.5 显示命令工具测试

#### 5.5.1 ExecuteMultipleDeviceCommands 测试

| 测试场景 | 用户输入 | 预期结果 |
|----------|----------|----------|
| **查看配置** | "在 R1 上显示 running-config" | 显示完整的运行配置 |
| **查看路由** | "在所有设备上显示路由表" | 批量显示各设备路由表 |
| **查看接口** | "显示 R1 接口状态" | 显示接口详细信息 |
| **自定义命令** | "在 R1 上执行 show version" | 执行指定显示命令 |

#### 5.5.2 输出格式测试

| 检查项 | 预期结果 |
|--------|----------|
| 命令输出格式化 | 使用代码块显示，便于阅读 |
| 多设备结果分隔 | 每个设备的结果明确分隔 |
| 错误处理 | 某设备执行失败时，其他设备结果正常显示 |

### 5.6 VPCS 工具测试

#### 5.6.1 VPCSMultiCommands 测试

| 测试场景 | 用户输入 | 预期结果 |
|----------|----------|----------|
| **配置 IP 地址** | "在 PC1 上配置 ip 192.168.1.1/24" | 配置成功 |
| **配置网关** | "在 PC1 上配置网关 192.168.1.254" | 配置成功 |
| **批量配置** | "配置所有 PC 的 IP 地址" | 批量配置成功 |
| **Ping 测试** | "在 PC1 上 ping 192.168.1.2" | 显示 Ping 结果 |
| **Traceroute** | "在 PC1 上 traceroute 8.8.8.8" | 显示路由跟踪结果 |

#### 5.6.2 并发执行测试

| 测试场景 | 操作 | 预期结果 |
|----------|------|----------|
| **多 PC 同时配置** | 对多个 PC 同时执行命令 | 命令并发执行，结果正确返回 |
| **执行顺序** | 检查日志 | 各命令按预期顺序执行 |

### 5.7 Linux Telnet 工具测试

#### 5.7.1 LinuxTelnetBatchTool 测试

| 测试场景 | 用户输入 | 预期结果 |
|----------|----------|----------|
| **执行单条命令** | "在 Debian1 上运行 ls -la" | 显示命令输出 |
| **查看系统信息** | "在 Debian1 上运行 uname -a" | 显示系统信息 |
| **批量执行** | "在所有 Linux 设备上检查内存" | 批量执行，显示各设备结果 |
| **复杂命令** | "在 Debian1 上运行 top -n 1" | 显示进程信息 |
| **网络测试** | "在 Debian1 上 ping google.com" | 显示 Ping 结果 |

#### 5.7.2 认证测试

| 测试场景 | 操作 | 预期结果 |
|----------|------|----------|
| **正确凭据** | 使用正确的用户名密码 | 成功登录并执行命令 |
| **错误凭据** | 使用错误的用户名密码 | 显示认证失败错误 |
| **无凭据** | 未配置 Linux 凭据 | 提示需要配置凭据 |

---

## 六、Help 页面测试

### 6.1 Help 页面显示测试

| 操作步骤 | 预期结果 |
|----------|----------|
| 点击侧边栏 "Help" 链接 | 页面切换到 Help 页面 |
| 滚动页面 | 显示完整的帮助内容 |
| 检查格式 | Markdown 内容正确渲染 |
| 检查链接 | 所有内部和外部链接可点击 |

### 6.2 Help 内容测试

| 检查项 | 预期结果 |
|--------|----------|
| 项目介绍 | 正确显示项目描述 |
| 功能列表 | 列出所有主要功能 |
| 使用说明 | 提供清晰的使用步骤 |
| 常见问题 | 包含常见问题解答 |
| 技术支持 | 提供联系方式或链接 |

---

## 七、边界和异常测试

### 7.1 输入边界测试

| 测试场景 | 操作 | 预期结果 |
|----------|------|----------|
| **空消息** | 发送空字符串或仅空格 | 提示需要输入内容 |
| **超长消息** | 发送 5000+ 字符的长消息 | 正常处理，不会崩溃 |
| **特殊字符** | 发送 emoji、特殊符号 | 正常处理 |
| **中文输入** | 发送中文消息 | AI 正确理解并响应 |
| **代码输入** | 发送代码块或命令 | 正确处理 |

### 7.2 连接异常测试

| 测试场景 | 操作 | 预期结果 |
|----------|------|----------|
| **GNS3 服务断开** | 关闭 GNS3 服务后操作 | 显示连接错误，提示检查服务 |
| **API Key 失效** | 使用无效或过期的 API Key | 显示认证错误 |
| **网络中断** | 断开网络后发送消息 | 显示网络错误 |
| **超时** | API 请求超时 | 显示超时提示 |

### 7.3 并发测试

| 测试场景 | 操作 | 预期结果 |
|----------|------|----------|
| **多会话切换** | 快速切换多个会话 | 每个会话数据正确，无混淆 |
| **快速发送** | 连续快速发送多条消息 | 消息按顺序处理，无丢失 |
| **多浏览器标签** | 在多个标签页同时打开应用 | 各会话独立运行 |

### 7.4 数据边界测试

| 测试场景 | 操作 | 预期结果 |
|----------|------|----------|
| **大量消息** | 会话中有 100+ 条消息 | 页面正常显示，滚动流畅 |
| **大量项目** | GNS3 中有 20+ 个项目 | 项目列表正常显示 |
| **大量设备** | 项目中有 50+ 个设备 | 操作正常，响应及时 |

---

## 八、持久化测试

### 8.1 会话持久化测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **会话保存** | 创建新会话并发送消息后关闭应用 | 重启应用后会话存在 |
| **消息历史** | 发送多条消息后重启 | 所有历史消息保留 |
| **会话标题** | 生成标题后重启 | 标题保持不变 |
| **选择的项目** | 选择项目后重启 | 项目状态保持 |

### 8.2 配置持久化测试

| 测试场景 | 操作步骤 | 预期结果 |
|----------|----------|----------|
| **配置保存** | 修改所有配置后重启 | 所有配置保持不变 |
| **.env 文件** | 检查 .env 文件内容 | 配置正确写入文件 |
| **删除 .env** | 删除 .env 后重启 | 应用使用默认配置 |

### 8.3 数据库检查

| 检查项 | 预期结果 |
|--------|----------|
| 数据库文件存在 | 项目根目录存在 `gns3_langgraph.db` |
| 会话数据 | SQLite 中存储了所有会话记录 |
| 消息数据 | 每个会话的消息正确存储 |

---

## 九、UI/UX 测试

### 9.1 响应式布局测试

| 测试场景 | 操作 | 预期结果 |
|----------|------|----------|
| **桌面视图** | 在 1920x1080 分辨率下查看 | 布局正常 |
| **小屏幕** | 在 1366x768 分辨率下查看 | 布局自适应 |
| **移动端** | 使用手机浏览器访问 | 布局适应移动端 |

### 9.2 交互测试

| 测试场景 | 操作 | 预期结果 |
|----------|------|----------|
| **侧边栏折叠** | 点击折叠按钮 | 侧边栏收起/展开 |
| **滚动行为** | 长消息列表滚动 | 滚动流畅 |
| **按钮状态** | 鼠标悬停按钮 | 视觉反馈 |
| **输入框** | 点击输入框 | 获得焦点，可输入 |

### 9.3 加载状态测试

| 检查项 | 预期结果 |
|--------|----------|
| 应用启动 | 显示加载动画 |
| AI 响应 | 显示加载指示 |
| 工具执行 | 显示执行中状态 |
| 错误提示 | 显示友好的错误信息 |

### 9.4 样式测试

| 检查项 | 预期结果 |
|--------|----------|
| 颜色搭配 | 颜色和谐，对比度足够 |
| 字体显示 | 字体清晰可读 |
| 图标显示 | 所有图标正确显示 |
| 间距布局 | 元素间距合理 |

---

## 十、测试报告模板

### 测试报告

```markdown
# GNS3 Copilot 测试报告

## 基本信息

| 项目 | 内容 |
|------|------|
| 测试日期 | YYYY-MM-DD |
| 测试人员 | [测试人员姓名] |
| 测试环境 | - Python: [版本] <br> - GNS3 Server: [版本] <br> - 操作系统: [系统] <br> - 浏览器: [浏览器及版本] |
| 应用版本 | [版本号] |

## 测试结果汇总

| 项目 | 数量 |
|------|------|
| 总测试用例 | XX |
| 通过 | XX |
| 失败 | XX |
| 跳过 | XX |
| 通过率 | XX% |

## 详细测试结果

### 1. 环境准备测试
| 用例编号 | 测试项 | 状态 | 备注 |
|----------|--------|------|------|
| 1.1 | Python 版本检查 | ✓/✗ | |
| 1.2 | 虚拟环境检查 | ✓/✗ | |
| 1.3 | GNS3 服务检查 | ✓/✗ | |
| ... | ... | ... | |

### 2. 应用启动测试
| 用例编号 | 测试项 | 状态 | 备注 |
|----------|--------|------|------|
| ... | ... | ... | |

### 3. Settings 页面测试
| 用例编号 | 测试项 | 状态 | 备注 |
|----------|--------|------|------|
| ... | ... | ... | |

... (其他测试模块)

## 发现的问题

### 问题 1
- **问题描述**: [详细描述]
- **严重程度**: 高/中/低
- **重现步骤**:
  1. [步骤 1]
  2. [步骤 2]
- **预期结果**: [预期结果]
- **实际结果**: [实际结果]
- **截图**: (如有)
- **相关日志**: (如有)

### 问题 2
...

## 改进建议

1. [建议 1]
2. [建议 2]

## 测试结论

[测试总结和结论]

## 签名

| 角色 | 姓名 | 日期 |
|------|------|------|
| 测试人员 | [签名] | [日期] |
| 审核人员 | [签名] | [日期] |
```

---

## 附录

### A. 常见测试命令

```bash
# 启动应用
gns3-copilot

# 启动应用（自定义端口）
gns3-copilot --server.port 8080

# 运行单元测试
python -m pytest tests/ -v

# 查看日志
tail -f log/gns3_copilot.log

# 检查数据库
sqlite3 gns3_langgraph.db "SELECT * FROM checkpoints LIMIT 5;"
```

### B. 测试环境准备

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate

# 安装依赖
pip install -e .

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填写配置
```

### C. 测试检查清单

- [ ] 环境准备完成
- [ ] GNS3 服务器运行正常
- [ ] 应用启动成功
- [ ] Settings 配置完成
- [ ] 会话管理正常
- [ ] 项目选择正常
- [ ] 基础聊天功能正常
- [ ] 所有工具功能正常
- [ ] Help 页面正常
- [ ] 边界异常处理正常
- [ ] 持久化功能正常
- [ ] UI/UX 正常

---

**文档版本**: 1.0  
**最后更新**: 2024-12-24  
**维护者**: GNS3 Copilot Team
