# ZCLAW 功能集成测试计划

> **版本**: v1.0
> **创建日期**: 2026-03-25
> **目标**: 对项目功能集成的完整性、可用性进行深度及广度测试

---

## 一、背景与目标

### 1.1 为什么需要这个测试计划

基于代码深度分析，ZCLAW 项目当前测试覆盖率约为 **40%**，存在以下关键问题：

| 问题 | 影响 |
|------|------|
| zclaw-types, zclaw-memory 无测试 | 基础层缺乏质量保障 |
| Hand Approval Flow 无 E2E 测试 | 核心安全功能未验证 |
| Skill Execution 无集成测试 | 自动化能力不可靠 |
| Identity Evolution 无测试 | 自演化功能未验证 |
| Rust 后端测试覆盖不均 | 关键路径缺乏验证 |

### 1.2 测试目标

- **短期**: 覆盖率从 40% 提升到 60%，补充关键路径测试
- **中期**: 覆盖率提升到 75%，建立完整测试金字塔
- **长期**: 覆盖率 80%+，集成 CI/CD 自动化测试

---

## 二、测试策略

### 2.1 测试金字塔

```
                    /\
                   /E2\      - 10% (关键用户旅程)
                  /2E \      - Playwright, ~15 tests
                 /-----\
                /       \
               /Integration\ - 30% (跨组件流程)
              /           \  - Vitest + Rust #[tokio::test]
             /-------------\
            /               \
           /    Unit Tests   \ - 60% (独立函数/组件)
          /                   \ - Vitest + #[cfg(test)]
         /---------------------\
```

### 2.2 优先级排序

| 优先级 | 测试类型 | 覆盖功能 |
|--------|----------|----------|
| P0 | 关键路径 | Agent Loop, Chat Flow, Hand Execution |
| P1 | 核心功能 | Skill Execution, Pipeline, Memory |
| P2 | 高级功能 | Intelligence Layer, Mesh, Team |
| P3 | 辅助功能 | UI Components, Config |

---

## 三、关键功能链路测试设计

### 3.1 Agent 创建 → 配置 → 对话 流程

**测试范围**: 用户创建 Agent → 配置模型/API → 发送消息 → 流式响应

**单元测试 (Rust)**:
```rust
// crates/zclaw-kernel/tests/agent_lifecycle.rs
- test_agent_creation_with_valid_config
- test_agent_creation_rejects_duplicate_id
- test_agent_deletion_cleans_up_session
```

**集成测试 (TypeScript)**:
```typescript
// tests/desktop/integration/agent-flow.test.ts
- creates agent and verifies persistence
- configures model and sends message
- handles concurrent agent switching
```

**E2E 测试 (Playwright)**:
```typescript
// desktop/tests/e2e/specs/agent-lifecycle.spec.ts
- AGENT-001: Full agent lifecycle (create → chat → delete)
```

### 3.2 Skill 发现 → 执行 流程

**测试范围**: 扫描 skills/ 目录 → 加载 SKILL.md → execute_skill 工具调用

**单元测试 (Rust)**:
```rust
// crates/zclaw-skills/tests/skill_execution.rs
- test_skill_loader_parses_valid_md
- test_skill_executor_validates_parameters
- test_skill_registry_lists_available_skills
```

**集成测试 (TypeScript)**:
```typescript
// tests/desktop/integration/skill-execution.test.ts
- loads skill catalog from gateway
- executes skill via execute_skill tool
```

### 3.3 Hand 触发 → 执行 → 审批 流程

**测试范围**: 选择 Hand → 配置参数 → 触发执行 → 审批/短路执行

**单元测试 (Rust)**:
```rust
// crates/zclaw-hands/tests/hand_execution.rs
- test_hand_registry_registers_and_executes
- test_hand_requires_approval_when_configured
- test_hand_cancellation_during_execution
```

**集成测试 (TypeScript)**:
```typescript
// tests/desktop/integration/hand-approval-flow.test.ts
- triggers hand and receives run ID
- handles needs_approval status
- rejects approval correctly
```

**E2E 测试 (Playwright)**:
```typescript
// desktop/tests/e2e/specs/hand-approval.spec.ts
- HAND-APPROVAL-001: Full approval flow
```

### 3.4 Pipeline 解析 → 执行 → 结果 流程

**测试范围**: YAML 解析 → 步骤执行 → 结果聚合

**单元测试 (Rust)**:
```rust
// crates/zclaw-pipeline/tests/pipeline_execution.rs
- test_pipeline_parser_accepts_valid_yaml
- test_pipeline_executor_runs_steps_sequentially
- test_pipeline_parallel_execution
- test_pipeline_cancellation
```

### 3.5 记忆存储 → 检索 流程

**测试范围**: 对话 → 提取 → 存储 → 检索 → 注入

**单元测试 (Rust)**:
```rust
// crates/zclaw-memory/tests/memory_operations.rs
- test_memory_store_creates_entry
- test_memory_search_by_content
- test_memory_importance_decay
```

### 3.6 心跳 → 反思 → 身份演化 流程

**测试范围**: 定时检查 → 分析模式 → 提案 → 审批

**集成测试 (TypeScript)**:
```typescript
// tests/desktop/identity-evolution.test.ts
- heartbeat tick updates status
- reflection generates proposals
```

---

## 四、测试覆盖现状与缺口

### 4.1 Rust Crate 测试现状

| Crate | 现有测试 | 覆盖率 | 缺口 |
|-------|---------|--------|------|
| zclaw-types | 0 | 0% | **CRITICAL** |
| zclaw-memory | 0 | 0% | **CRITICAL** |
| zclaw-runtime | ~29 | ~40% | 需补充 agent loop |
| zclaw-kernel | ~8 | ~25% | 需补充 registry |
| zclaw-skills | ~18 | ~60% | 良好 |
| zclaw-hands | ~5 | ~15% | **需补充** |
| zclaw-protocols | ~3 | ~30% | 部分 |
| zclaw-pipeline | ~14 | ~50% | 良好 |

### 4.2 前端测试现状

| Store | 现有测试 | 缺口 |
|-------|---------|------|
| chatStore | 15+ | 良好 |
| gatewayStore | 10+ | 良好 |
| handStore | 5 | 需补充审批流程 |
| meshStore | 0 | **需新增** |
| personaStore | 0 | **需新增** |

---

## 五、测试环境配置

### 5.1 Mock 策略

```typescript
// tests/fixtures/mock-llm-driver.ts
export class MockLlmDriver {
  async complete(request: CompletionRequest): Promise<CompletionResponse> {
    return { content: [{ type: 'text', text: 'Mock response' }], stop_reason: 'end_turn' };
  }
}
```

```rust
// crates/zclaw-runtime/src/driver/mock.rs
pub struct MockLlmDriver {
    responses: RwLock<Vec<CompletionResponse>>,
}
```

### 5.2 测试数据目录结构

```
tests/
├── fixtures/
│   ├── skills/
│   │   └── test-skill/SKILL.md
│   ├── hands/
│   │   └── test-hand.HAND.toml
│   ├── pipelines/
│   │   ├── simple.yaml
│   │   └── parallel.yaml
│   └── conversations/
│       └── sample-chat.json
├── mock-server.ts
└── setup.ts
```

---

## 六、执行计划

### 6.1 短期 (1-2 周) - 补充关键缺口

| 任务 | 优先级 | 工作量 | 关键文件 |
|------|--------|--------|----------|
| zclaw-types 单元测试 | P0 | 2d | `crates/zclaw-types/src/*.rs` |
| zclaw-memory 单元测试 | P0 | 2d | `crates/zclaw-memory/src/*.rs` |
| Hand Approval E2E 测试 | P0 | 1d | `desktop/tests/e2e/specs/hand-approval.spec.ts` |
| Skill Execution 集成测试 | P1 | 1d | `tests/desktop/integration/skill-execution.test.ts` |

### 6.2 中期 (3-4 周) - 提升覆盖率到 70%

| 任务 | 优先级 | 工作量 | 关键文件 |
|------|--------|--------|----------|
| zclaw-hands 单元测试 | P1 | 2d | `crates/zclaw-hands/src/*.rs` |
| Pipeline 执行测试 | P1 | 2d | `crates/zclaw-pipeline/src/*.rs` |
| Intelligence Layer 测试 | P2 | 3d | `desktop/src-tauri/src/intelligence/*.rs` |
| meshStore 测试 | P2 | 1d | `tests/desktop/meshStore.test.ts` |
| personaStore 测试 | P2 | 1d | `tests/desktop/personaStore.test.ts` |

### 6.3 长期 (5-8 周) - CI/CD 集成

| 任务 | 优先级 | 工作量 |
|------|--------|--------|
| 覆盖率报告设置 | P2 | 2d |
| 性能基准测试 | P3 | 3d |
| 并发压力测试 | P3 | 2d |
| 测试模式文档 | P3 | 1d |

---

## 七、关键测试文件清单

### 7.1 需要新增的测试文件

**Rust 测试**:
- `crates/zclaw-types/src/id.rs` - 添加 `#[cfg(test)] mod tests`
- `crates/zclaw-types/src/message.rs` - 添加测试
- `crates/zclaw-memory/src/store.rs` - 添加测试
- `crates/zclaw-hands/tests/hand_registry_test.rs`
- `crates/zclaw-hands/tests/browser_hand_test.rs`

**TypeScript 集成测试**:
- `tests/desktop/integration/agent-flow.test.ts`
- `tests/desktop/integration/skill-execution.test.ts`
- `tests/desktop/integration/hand-approval-flow.test.ts`
- `tests/desktop/integration/pipeline-execution.test.ts`

**E2E 测试**:
- `desktop/tests/e2e/specs/agent-lifecycle.spec.ts`
- `desktop/tests/e2e/specs/hand-approval.spec.ts`
- `desktop/tests/e2e/specs/skill-discovery.spec.ts`
- `desktop/tests/e2e/specs/identity-evolution.spec.ts`

**新增 Store 测试**:
- `tests/desktop/meshStore.test.ts`
- `tests/desktop/personaStore.test.ts`

### 7.2 需要扩展的现有文件

- `tests/desktop/chatStore.test.ts` - 添加流式响应测试
- `tests/desktop/gatewayStore.test.ts` - 添加重连测试
- `desktop/tests/e2e/specs/core-features.spec.ts` - 添加审批流程场景

---

## 八、验证方法

### 8.1 单元测试验证

```bash
# Rust 单元测试
cargo test --workspace

# TypeScript 单元测试
pnpm test
```

### 8.2 集成测试验证

```bash
# 运行集成测试
pnpm test:integration

# 特定测试文件
pnpm vitest run tests/desktop/integration/
```

### 8.3 E2E 测试验证

```bash
# 启动应用
pnpm tauri dev

# 运行 E2E 测试
pnpm test:e2e
```

### 8.4 覆盖率报告

```bash
# Rust 覆盖率
cargo tarpaulin --workspace

# TypeScript 覆盖率
pnpm test:coverage
```

---

## 九、成功标准

| 指标 | 当前 | 目标 |
|------|------|------|
| Rust 测试覆盖率 | ~40% | **75%** |
| TypeScript 测试覆盖率 | ~60% | **80%** |
| E2E 关键路径覆盖 | 50% | **100%** |
| CI/CD 集成 | 部分 | **完整** |

---

## 十、风险与缓解

| 风险 | 缓解措施 |
|------|----------|
| LLM API 测试成本高 | 使用 Mock Driver |
| E2E 测试不稳定 | 添加重试机制和等待策略 |
| 测试数据管理复杂 | 使用 fixtures 目录集中管理 |
| 并发测试干扰 | 使用隔离的测试数据库 |