# @claude-flow/testing 中文文档

规范地址：https://npmcn.com/package/%40claude-flow/testing/

版本：3\.0\.0
npm 元数据更新时间：2026-09-28T21:01:44.275Z
中文译文更新时间：2026-11-10T00:15:24.583Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40claude-flow/testing
原文对照：https://npmcn.com/package/%40claude-flow/testing/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1 MB，146 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：vitest \>=4\.0\.16，@claude-flow/swarm ^3\.0\.0，@claude-flow/memory ^3\.0\.0，@claude-flow/shared ^3\.0\.0
- 首次发布：2026-01-06T21:47:41.756Z
- 最新版本发布：2026-09-28T20:56:14.825Z
- 近 30 天下载量：2618（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

测试模块 - TDD伦敦学校框架、测试公用事业、固定装置和模拟服务V3 Claude-Flow

## 安装

```sh
npm install @claude-flow/testing
```

也可以使用：`pnpm add @claude-flow/testing`、`yarn add @claude-flow/testing`、`bun add @claude-flow/testing`

## README

# @ claude- flow/ 测试

[![npm version](https://img.shields.io/npm/v/@claude-flow/testing.svg)](https://www.npmjs.com/package/@claude-flow/testing) [![npm downloads](https://img.shields.io/npm/dm/@claude-flow/testing.svg)](https://www.npmjs.com/package/@claude-flow/testing) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/) [![TDD](https://img.shields.io/badge/TDD-London%20School-purple.svg)](https://github.com/ruvnet/claude-flow) [![ADR-008](https://img.shields.io/badge/ADR--008-Vitest-green.svg)](https://vitest.dev/)

> V3 Claude-Flow模块综合测试框架. 实施伦敦学校TDD模式,包括行为验证、共享固定装置和模拟服务.

基于ADR-008 (Vitet over Jest).

## 安装

```bash
npm install @claude-flow/testing vitest --save-dev
```

## 快速启动

```typescript
import {
  setupV3Tests,
  createMockApplication,
  agentConfigs,
  swarmConfigs,
  waitFor,
} from '@claude-flow/testing';

// Configure test environment
setupV3Tests();

describe('MyModule', () => {
  const app = createMockApplication();

  beforeEach(() => {
    // Mocks are automatically reset
  });

  it('should spawn an agent', async () => {
    const result = await app.agentLifecycle.spawn(agentConfigs.queenCoordinator);

    expect(result.success).toBe(true);
    expect(result.agent.type).toBe('queen-coordinator');
  });
});
```

## 目录结构

```
src/
├── fixtures/           # Pre-defined test data
│   ├── agent-fixtures.ts    # Mock agents, configs
│   ├── memory-fixtures.ts   # Memory entries, backends
│   ├── swarm-fixtures.ts    # Swarm configs, topologies
│   └── mcp-fixtures.ts      # MCP tools, contexts
├── helpers/            # Test utilities
│   ├── test-utils.ts        # waitFor, retry, timeout
│   ├── mock-factory.ts      # Factory functions for mocks
│   ├── assertion-helpers.ts # Custom Vitest matchers
│   └── setup-teardown.ts    # Global setup/teardown
├── mocks/              # Mock service implementations
│   ├── mock-services.ts     # AgentDB, SwarmCoordinator, etc.
│   └── mock-mcp-client.ts   # MCP client for CLI testing
├── setup.ts            # Global test configuration
└── index.ts            # Main exports
```

## 固定设备

### 代理定型器

```typescript
import {
  agentConfigs,
  agentInstances,
  createAgentConfig,
  createAgentInstance,
  createV3SwarmAgentConfigs,
  createMockAgent,
  createMockV3Swarm,
} from '@claude-flow/testing';

// Pre-defined configs
const queen = agentConfigs.queenCoordinator;
const coder = agentConfigs.coder;

// Create with overrides
const customAgent = createAgentConfig('coder', {
  name: 'Custom Coder',
  priority: 90,
});

// Full V3 15-agent swarm
const swarmConfigs = createV3SwarmAgentConfigs();

// Mock agents with vitest mocks
const mockAgent = createMockAgent('security-architect');
mockAgent.execute.mockResolvedValue({ success: true });
```

### 内存修复

```typescript
import {
  memoryEntries,
  searchResults,
  learnedPatterns,
  hnswConfigs,
  memoryBackendConfigs,
  createMemoryEntry,
  createVectorQuery,
  generateMockEmbedding,
  createMemoryBatch,
} from '@claude-flow/testing';

// Pre-defined entries
const pattern = memoryEntries.agentPattern;
const securityRule = memoryEntries.securityRule;

// Create with overrides
const entry = createMemoryEntry('agentPattern', {
  key: 'custom:pattern:001',
});

// Generate embeddings
const embedding = generateMockEmbedding(384, 'my-seed');

// Create batch for performance testing
const batch = createMemoryBatch(10000, 'semantic');
```

### 灭火器

```typescript
import {
  swarmConfigs,
  swarmStates,
  swarmTasks,
  swarmMessages,
  coordinationResults,
  createSwarmConfig,
  createSwarmTask,
  createSwarmMessage,
  createConsensusRequest,
  createMockSwarmCoordinator,
} from '@claude-flow/testing';

// Pre-defined configs
const v3Config = swarmConfigs.v3Default;
const minimalConfig = swarmConfigs.minimal;

// Create with overrides
const customConfig = createSwarmConfig('v3Default', {
  maxAgents: 20,
  coordination: {
    consensusProtocol: 'pbft',
    heartbeatInterval: 500,
    electionTimeout: 3000,
  },
});

// Mock coordinator
const coordinator = createMockSwarmCoordinator();
await coordinator.initialize(v3Config);
```

### MCP 固定器

```typescript
import {
  mcpTools,
  mcpResources,
  mcpPrompts,
  mcpServerConfigs,
  mcpToolResults,
  mcpErrors,
  createMCPTool,
  createMCPRequest,
  createMCPResponse,
  createMockMCPClient,
} from '@claude-flow/testing';

// Pre-defined tools
const swarmInit = mcpTools.swarmInit;
const agentSpawn = mcpTools.agentSpawn;

// Mock client
const client = createMockMCPClient();
await client.connect();
const result = await client.callTool('swarm_init', { topology: 'mesh' });
```

## 测试工具

### 同步公用事业

```typescript
import {
  waitFor,
  waitUntilChanged,
  retry,
  withTimeout,
  sleep,
  parallelLimit,
} from '@claude-flow/testing';

// Wait for condition
await waitFor(() => element.isVisible(), { timeout: 5000 });

// Wait for value to change
await waitUntilChanged(() => counter.value, { from: 0 });

// Retry with exponential backoff
const result = await retry(
  async () => await fetchData(),
  { maxAttempts: 3, backoff: 100 }
);

// Timeout wrapper
await withTimeout(async () => await longOp(), 5000);

// Parallel with concurrency limit
const results = await parallelLimit(
  items.map(item => () => processItem(item)),
  5 // max 5 concurrent
);
```

### 时间控制

```typescript
import { createMockClock, measureTime } from '@claude-flow/testing';

// Mock clock for time-dependent tests
const clock = createMockClock();
clock.install();
clock.tick(1000); // Advance by 1 second
clock.uninstall();

// Measure execution time
const { result, duration } = await measureTime(async () => {
  return await expensiveOperation();
});
```

### 事件发送器

```typescript
import { createTestEmitter } from '@claude-flow/testing';

const emitter = createTestEmitter<{ message: string; count: number }>();

const handler = vi.fn();
emitter.on('message', handler);
emitter.emit('message', 'hello');

expect(handler).toHaveBeenCalledWith('hello');
```

## 雾工厂

### 应用程序模拟

```typescript
import {
  createMockApplication,
  createMockEventBus,
  createMockTaskManager,
  createMockAgentLifecycle,
  createMockMemoryService,
  createMockSecurityService,
  createMockSwarmCoordinator,
  createMockLogger,
} from '@claude-flow/testing';

// Full application with all mocks
const app = createMockApplication();

// Individual service mocks
const eventBus = createMockEventBus();
const taskManager = createMockTaskManager();
const security = createMockSecurityService();

// Use in tests
await app.taskManager.create({ name: 'Test', type: 'coding', payload: {} });
expect(app.taskManager.create).toHaveBeenCalled();

// Access tracked state
expect(app.eventBus.publishedEvents).toHaveLength(1);
expect(app.taskManager.tasks.size).toBe(1);
```

## 模拟服务

### 模拟代理数据库

```typescript
import { MockAgentDB } from '@claude-flow/testing';

const db = new MockAgentDB();

// Insert vectors
await db.insert('vec-1', embedding, { type: 'pattern' });

// Search
const results = await db.search(queryEmbedding, 10, 0.7);

// Verify calls
expect(db.insert).toHaveBeenCalledWith('vec-1', expect.any(Array), expect.any(Object));
```

### 迷宫协调员

```typescript
import { MockSwarmCoordinator } from '@claude-flow/testing';

const coordinator = new MockSwarmCoordinator();

await coordinator.initialize({ topology: 'hierarchical-mesh' });
await coordinator.addAgent({ type: 'coder', name: 'Coder-1' });
const result = await coordinator.coordinate({ id: 'task-1', type: 'coding', payload: {} });

expect(coordinator.getState().agentCount).toBe(1);
expect(result.success).toBe(true);
```

### 模拟MCPClient

```typescript
import { MockMCPClient, createStandardMockMCPClient } from '@claude-flow/testing';

// Standard client with common tools
const client = createStandardMockMCPClient();
await client.connect();

// Custom tool handlers
client.setToolHandler('swarm_init', async (params) => ({
  content: [{ type: 'text', text: JSON.stringify({ swarmId: 'test' }) }],
}));

const result = await client.callTool('swarm_init', { topology: 'mesh' });

// Verify request history
expect(client.getRequestHistory()).toHaveLength(1);
expect(client.getLastRequest()?.method).toBe('tools/call');
```

## 请求

### 标准请求

```typescript
import {
  assertEventPublished,
  assertEventOrder,
  assertMocksCalledInOrder,
  assertV3PerformanceTargets,
  assertValidStateTransition,
  assertNoSensitiveData,
} from '@claude-flow/testing';

// Event assertions
assertEventPublished(mockEventBus, 'UserCreated', { userId: '123' });
assertEventOrder(mockEventBus.publish, ['UserCreated', 'EmailSent']);

// Mock order
assertMocksCalledInOrder([mockValidate, mockSave, mockNotify]);

// Performance targets
assertV3PerformanceTargets({
  searchSpeedup: 160,
  flashAttentionSpeedup: 3.5,
  memoryReduction: 0.55,
});

// State transitions
assertValidStateTransition('pending', 'running', {
  pending: ['running', 'cancelled'],
  running: ['completed', 'failed'],
});

// Security
assertNoSensitiveData(mockLogger.logs, ['password', 'token', 'secret']);
```

### 自定义比对器

```typescript
import { registerCustomMatchers } from '@claude-flow/testing';

// Register in setup
registerCustomMatchers();

// Use in tests
expect(mockFn).toHaveBeenCalledWithPattern({ userId: expect.any(String) });
expect(event).toHaveEventType('UserCreated');
expect(metrics).toMeetV3PerformanceTargets();
```

## 设置拆分( D)

### 全球测试设置

```typescript
import { setupV3Tests, configureTestEnvironment } from '@claude-flow/testing';

// Simple setup
setupV3Tests();

// Custom configuration
configureTestEnvironment({
  resetMocks: true,
  fakeTimers: true,
  suppressConsole: ['log', 'warn'],
  env: {
    NODE_ENV: 'test',
    DEBUG: 'false',
  },
});
```

### 测试背景

```typescript
import { createSetupContext, createTestScope } from '@claude-flow/testing';

// Setup context with cleanup
const ctx = createSetupContext();
ctx.addCleanup(() => server.close());
ctx.registerResource(database);
// ... run tests
await ctx.runCleanup();

// Isolated test scope
const scope = createTestScope();
scope.addMock(mockService);
await scope.run(async () => {
  // test code - mocks auto-cleared after
});
```

### 性能测试

```typescript
import { createPerformanceTestHelper } from '@claude-flow/testing';

const perf = createPerformanceTestHelper();

perf.startMeasurement('search');
await search(query);
const duration = perf.endMeasurement('search');

// Get statistics
const stats = perf.getStats('search');
console.log(`Avg: ${stats.avg}ms, P95: ${stats.p95}ms`);
```

## 绩效目标

测试框架包括对V3性能目标的断言:

| 度量衡 | 目标 |
| --- | --- |
| 搜索加速 | 150辆 -- -- 12 500辆 |
| 闪出注意速度 | 2.49x - 7.47x (英语) |
| 减少内存 | \>= 50% |
| 启动时间 | < 500分钟 |
| 反应时间 | < 100 分钟 |

```typescript
import { assertV3PerformanceTargets, TEST_CONFIG } from '@claude-flow/testing';

// Assert targets
assertV3PerformanceTargets({
  searchSpeedup: 160,
  flashAttentionSpeedup: 3.5,
  memoryReduction: 0.55,
  startupTimeMs: 450,
  responseTimeMs: 80,
});

// Access constants
console.log(TEST_CONFIG.FLASH_ATTENTION_SPEEDUP_MIN); // 2.49
console.log(TEST_CONFIG.AGENTDB_SEARCH_IMPROVEMENT_MAX); // 12500
```

## 最佳做法

### 1\. 使用伦敦学校TDD

```typescript
// Arrange mocks before acting
const mockRepo = createMock<UserRepository>();
mockRepo.findById.mockResolvedValue(user);

// Act
await service.processUser('123');

// Assert behavior (not implementation)
expect(mockRepo.findById).toHaveBeenCalledWith('123');
expect(mockNotifier.notify).toHaveBeenCalledBefore(mockRepo.save);
```

### 2\. 使用 Fixtures 超越内置数据

```typescript
// Good - use fixtures
const agent = agentConfigs.queenCoordinator;
const task = createSwarmTask('securityScan');

// Avoid - inline data
const agent = { type: 'queen-coordinator', name: 'Test', capabilities: [] };
```

### 3\. 隔离试验

```typescript
// Use fresh mocks per test
beforeEach(() => {
  vi.clearAllMocks();
});

// Or use test scope
const scope = createTestScope();
await scope.run(async () => {
  // isolated test
});
```

### 4\. 试验行为,不执行

```typescript
// Good - behavior verification
expect(mockEventBus.publish).toHaveBeenCalledWith(
  expect.objectContaining({ type: 'UserCreated' })
);

// Avoid - implementation details
expect(service._internalQueue.length).toBe(1);
```

## 许可证

麻省理工学院

## 常见问题

### @claude-flow/testing 是什么？

测试模块 - TDD伦敦学校框架、测试公用事业、固定装置和模拟服务V3 Claude-Flow

### 如何安装 @claude-flow/testing？

在项目目录运行 npm install @claude-flow/testing，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vitest（\>=4\.0\.16）、@claude-flow/swarm（^3\.0\.0）、@claude-flow/memory（^3\.0\.0）、@claude-flow/shared（^3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @claude-flow/testing 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @claude-flow/testing 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @claude-flow/testing 可以商用吗？

@claude-flow/testing 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @claude-flow/testing 的下载量有多少？

根据 npm 官方下载统计，@claude-flow/testing 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,618 次，日均约 87 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @claude-flow/testing 还在维护吗？

最新版本 3\.0\.0 发布于 2026/09/29（1 个月前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/01/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。