bf6d81f9c6
Some checks failed
CI / Rust Check (push) Has been cancelled
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
style: 统一代码格式和注释风格 docs: 更新多个功能文档的完整度和状态 feat(runtime): 添加路径验证工具支持 fix(pipeline): 改进条件判断和变量解析逻辑 test(types): 为ID类型添加全面测试用例 chore: 更新依赖项和Cargo.lock文件 perf(mcp): 优化MCP协议传输和错误处理
369 lines
9.7 KiB
Markdown
369 lines
9.7 KiB
Markdown
# 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 目录集中管理 |
|
||
| 并发测试干扰 | 使用隔离的测试数据库 |
|