# Agent ROS Bridge - 功能不完整时的测试先行策略

> **分析日期**: 2026-02-26  
> **当前状态**: v0.5.0，核心功能已可用，部分模块为骨架/占位实现

---

## 当前项目状态快照

| 模块 | 完成度 | 测试可行性 |
|------|--------|------------|
| **WebSocket Transport** | ✅ 90% | **可立即测试** - 核心功能完整 |
| **MQTT Transport** | ✅ 85% | **可立即测试** - 主要功能可用 |
| **Config System** | ✅ 95% | **可立即测试** - 配置加载稳定 |
| **Bridge Core** | ✅ 80% | **可立即测试** - 生命周期管理可用 |
| **JWT Auth** | ✅ 75% | **可立即测试** - 认证流程完整 |
| **ROS2 Connector** | 🔧 60% | **可并行测试** - 刚修复publish/subscribe |
| **gRPC Transport** | 🔧 55% | **可并行测试** - 刚完成服务注册 |
| **Safety Manager** | ✅ 70% | **可立即测试** - 策略框架完整 |
| **Agent Memory** | ✅ 80% | **可立即测试** - SQLite后端可用 |
| **Fleet Management** | 🔧 50% | **需要Mock** - 部分功能占位 |
| **Tool Discovery** | ⚠️ 40% | **契约测试先行** - 接口定义优先 |
| **LangChain Adapter** | ✅ 65% | **可Mock测试** - 适配器可独立测试 |
| **MCP Transport** | ✅ 60% | **可Mock测试** - JSON-RPC可模拟 |

---

## 三阶段测试先行方案

### Phase 1: 立即启动 (本周可完成)

**目标**: 为核心稳定模块建立测试基线，不阻塞开发

```
┌─────────────────────────────────────────────────────────────┐
│  NOW - 不依赖功能完整，测试与开发解耦                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ✅ 单元测试: Config, Message, Identity 等数据类            │
│     → 零依赖，验证序列化/反序列化、边界条件                  │
│                                                             │
│  ✅ 单元测试: Transport 抽象层                              │
│     → Mock底层连接，测试消息路由逻辑                        │
│                                                             │
│  ✅ 单元测试: Auth (JWT encode/decode)                      │
│     → 纯函数测试，不依赖服务器                              │
│                                                             │
│  ✅ 单元测试: SafetyManager 策略评估                        │
│     → 纯逻辑测试，Mock机器人状态                            │
│                                                             │
│  ✅ 集成测试: WebSocket 协议解析                            │
│     → 使用 websockets 库直接测试，无需完整Bridge            │
│                                                             │
│  ✅ 契约测试: WebSocket/MCP API 接口定义                    │
│     → 先定义期望契约，驱动后端实现                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**具体可立即编写的测试:**

```python
# 1. 配置系统 - 立即可以测试
# tests/unit/test_config.py - 可立即编写
def test_config_env_override():
    """测试环境变量覆盖配置文件"""
    with mock.patch.dict(os.environ, {"BRIDGE_WEBSOCKET_PORT": "9999"}):
        config = ConfigLoader.from_file_or_env("config.yaml")
        assert config.transports["websocket"].port == 9999

# 2. 消息数据类 - 立即可以测试  
# tests/unit/test_messages.py - 可立即编写
def test_message_correlation_id_propagation():
    """测试消息关联ID在响应中保留"""
    req = Message(header=Header(message_id="req-123"))
    response = create_response(request=req, data={})
    assert response.header.correlation_id == "req-123"

# 3. Transport抽象层 - Mock测试
# tests/unit/test_transport_manager.py - 可立即编写
@pytest.mark.asyncio
async def test_transport_manager_routes_by_message_target():
    """测试TransportManager根据target路由到正确Transport"""
    manager = TransportManager()
    
    # Mock两个transport
    ws_transport = MockTransport(name="websocket")
    mqtt_transport = MockTransport(name="mqtt")
    
    manager.register(ws_transport)
    manager.register(mqtt_transport)
    
    # 发送目标为mqtt的消息
    msg = Message(header=Header(target="robot_1"))
    msg.metadata = {"preferred_transport": "mqtt"}
    
    await manager.send(msg)
    
    # 验证只有mqtt transport收到
    assert mqtt_transport.sent_messages == [msg]
    assert ws_transport.sent_messages == []
```

---

### Phase 2: 并行开发 (与功能开发同步)

**目标**: 新功能开发与测试编写同步进行，采用「红-绿-重构」TDD循环

```
┌─────────────────────────────────────────────────────────────┐
│  PARALLEL - 新功能开发与测试同步                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  🔧 ROS2 Connector publish/subscribe - 刚修复               │
│     → 现在编写集成测试验证修复                              │
│     → 使用 testcontainers 启动真实ROS2环境                  │
│                                                             │
│  🔧 gRPC Transport - 刚完成服务注册                         │
│     → 编写proto兼容性测试                                   │
│     → 使用 grpclib 测试客户端调用                           │
│                                                             │
│  🔧 Fleet Management - 部分实现                            │
│     → 契约测试先行：定义任务分配API契约                     │
│     → Mock未实现部分，测试已实现逻辑                        │
│                                                             │
│  🔧 Tool Discovery - 仅接口                                │
│     → 接口契约测试：MCP/OpenAI格式转换                      │
│     → Mock ROS introspection 返回值                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**TDD循环示例 (Fleet功能):**

```python
# Step 1: 先写测试 (即使功能不存在)
# tests/unit/fleet/test_task_assignment.py
async def test_task_assigned_to_capable_robot():
    """测试：任务分配给具备能力的机器人"""
    fleet = RobotFleet("test")
    
    # 添加两个机器人，只有robot_2有manipulate能力
    robot_1 = MockRobot(robot_id="r1", capabilities=["navigate"])
    robot_2 = MockRobot(robot_id="r2", capabilities=["navigate", "manipulate"])
    
    await fleet.add_robot(robot_1)
    await fleet.add_robot(robot_2)
    
    # 分配需要manipulate能力的任务
    task = Task(action="pick_object", required_capabilities=["manipulate"])
    assigned = await fleet.assign_task(task)
    
    # 期望：分配给robot_2
    assert assigned.robot_id == "r2"
    assert robot_2.assigned_tasks == [task]
    assert robot_1.assigned_tasks == []

# Step 2: 运行测试 → 失败 (功能未实现)
# Step 3: 实现最小功能使测试通过
# Step 4: 重构优化
```

---

### Phase 3: 功能稳定后补充 (技术债务清理后)

**目标**: 等功能骨架填实后，补充E2E和性能测试

```
┌─────────────────────────────────────────────────────────────┐
│  LATER - 功能完整后再投入                                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ⏸️ 端到端测试 (E2E)                                        │
│     → 需要所有模块协同工作                                  │
│     → 等待：Tool Discovery完成，Fleet完整实现               │
│                                                             │
│  ⏸️ 性能基准测试                                            │
│     → 需要稳定实现才能建立有意义的基准                      │
│     → 等待：ROS2 Connector优化完成                          │
│                                                             │
│  ⏸️ 混沌测试 / 故障注入                                     │
│     → 需要系统完整才能验证韧性                              │
│     → 等待：所有错误处理路径实现                            │
│                                                             │
│  ⏸️ 兼容性矩阵测试                                          │
│     → API稳定后再投入                                       │
│     → 等待：v1.0 API冻结                                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## 当前建议的测试优先级

### 🔴 P0 - 本周立即实施

1. **Config系统单元测试** 
   - 环境变量覆盖、YAML/JSON解析、嵌套属性访问
   - 目的：配置是系统的入口，先保证稳定

2. **Message/数据类单元测试**
   - 序列化/反序列化、UUID生成、时间戳处理
   - 目的：数据层是系统基础

3. **TransportManager路由逻辑**
   - Mock transport，测试消息分发逻辑
   - 目的：核心消息路由，不依赖具体协议

4. **JWT Auth单元测试**
   - Token生成/验证、过期处理、算法验证
   - 目的：安全基础，纯函数可独立测试

### 🟡 P1 - 下周并行实施

5. **WebSocket Transport集成测试**
   - 使用 pytest-asyncio + websockets 客户端
   - 目的：验证我们刚修复的债务

6. **ROS2 Connector集成测试**
   - 使用 testcontainers 启动ROS2容器
   - 目的：验证刚修复的publish/subscribe

7. **gRPC契约测试**
   - 定义proto契约，验证服务注册
   - 目的：确保gRPC实现符合契约

8. **Safety Manager逻辑测试**
   - Mock机器人状态，测试策略评估
   - 目的：安全关键路径

### 🟢 P2 - 后续补充

9. **Fleet管理契约测试**
   - 定义任务分配API契约
   - 目的：接口先行，驱动实现

10. **E2E测试框架搭建**
    - Docker Compose编排，等待功能完整

---

## 实施路线图调整

| 原方案 | 调整后 | 原因 |
|--------|--------|------|
| Phase 1: 1周补全单元测试 | ✅ **本周开始** | 数据类/配置类不依赖功能完整 |
| Phase 2: 1周契约+集成测试 | 🔧 **与开发并行** | ROS2/gRPC刚修复，立即验证 |
| Phase 3: 1周性能+安全测试 | ⏸️ **功能稳定后** | 基准测试需要稳定实现 |
| Phase 4: 持续TDD | ✅ **立即开始** | 新功能采用TDD，老功能补测试 |

---

## 本周可交付的测试代码

我可以在接下来的1-2小时内为你生成：

1. **tests/unit/test_config_comprehensive.py** (20+ 测试用例)
2. **tests/unit/test_core_message_routing.py** (15+ 测试用例)
3. **tests/unit/test_auth_security.py** (10+ 安全测试)
4. **tests/integration/test_websocket_transport.py** (集成测试)
5. **tests/contract/test_websocket_api.py** (契约定义)

**这些测试：**
- ✅ 不依赖功能100%完成
- ✅ 使用Mock隔离未完成模块
- ✅ 立即可以运行并验证核心逻辑
- ✅ 为后续重构提供安全网

---

**确认后我将立即开始编写 Phase 1 (P0级别) 的测试代码。**

确认问题：
1. 上述三阶段策略是否符合当前情况？
2. 是否从 P0 (Config/Message/Auth单元测试) 开始？
3. 是否需要我先提交当前债务清理的代码，再切新分支写测试？
