π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
checkpoint: File edit:
rUvb6fc024fe927
diff --git a/v3/@claude-flow/testing/README.md b/v3/@claude-flow/testing/README.mdnew file mode 100644index 0000000000..7e08ff60fd--- /dev/null+++ b/v3/@claude-flow/testing/README.md@@ -0,0 +1,540 @@+# @claude-flow/testing++Comprehensive testing framework for V3 Claude-Flow modules. Implements London School TDD patterns with behavior verification, shared fixtures, and mock services.++Based on ADR-008 (Vitest over Jest).++## Installation++```bash+npm install @claude-flow/testing vitest --save-dev+```++## Quick Start++```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');+ });+});+```++## Directory Structure++```+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+```++## Fixtures++### Agent Fixtures++```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 });+```++### Memory Fixtures++```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');+```++### Swarm Fixtures++```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 Fixtures++```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' });+```++## Test Utilities++### Async Utilities++```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+);+```++### Time Control++```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();+});+```++### Event Emitter++```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');+```++## Mock Factory++### Application Mocks++```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);+```++## Mock Services++### MockAgentDB++```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));+```++### MockSwarmCoordinator++```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);+```++### MockMCPClient++```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');+```++## Assertions++### Standard Assertions++```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']);+```++### Custom Vitest Matchers++```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();+```++## Setup & Teardown++### Global Test Setup++```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',+ },+});+```++### Test Context++```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+});+```++### Performance Testing++```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`);+```++## Performance Targets++The testing framework includes assertions for V3 performance targets:++| Metric | Target |+|--------|--------|+| Search Speedup | 150x - 12,500x |+| Flash Attention Speedup | 2.49x - 7.47x |+| Memory Reduction | >= 50% |+| Startup Time | < 500ms |+| Response Time | < 100ms |++```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+```++## Best Practices++### 1. Use London School 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. Use Fixtures Over Inline Data++```typescript+// Good - use fixtures+const agent = agentConfigs.queenCoordinator;+const task = createSwarmTask('securityScan');++// Avoid - inline data+const agent = { type: 'queen-coordinator', name: 'Test', capabilities: [] };+```++### 3. Isolate Tests++```typescript+// Use fresh mocks per test+beforeEach(() => {+ vi.clearAllMocks();+});++// Or use test scope+const scope = createTestScope();+await scope.run(async () => {+ // isolated test+});+```++### 4. Test Behavior, Not Implementation++```typescript+// Good - behavior verification+expect(mockEventBus.publish).toHaveBeenCalledWith(+ expect.objectContaining({ type: 'UserCreated' })+);++// Avoid - implementation details+expect(service._internalQueue.length).toBe(1);+```++## License++MITdiff --git a/v3/@claude-flow/testing/package.json b/v3/@claude-flow/testing/package.jsonindex f3cf0d0a02..49ab1d0955 100644--- a/v3/@claude-flow/testing/package.json+++ b/v3/@claude-flow/testing/package.json@@ -2,16 +2,31 @@"name": "@claude-flow/testing","version": "3.0.0-alpha.1","type": "module",- "description": "Testing module - TDD London School framework, test utilities",+ "description": "Testing module - TDD London School framework, test utilities, fixtures, and mock services for V3 Claude-Flow","main": "src/index.ts","types": "src/index.ts","exports": {".": "./src/index.ts","./helpers": "./src/helpers/index.ts",- "./fixtures": "./src/fixtures/index.ts"+ "./fixtures": "./src/fixtures/index.ts",+ "./mocks": "./src/mocks/index.ts",+ "./setup": "./src/setup.ts"},"scripts": {- "build": "tsc"+ "build": "tsc",+ "typecheck": "tsc --noEmit"+ },+ "keywords": [+ "claude-flow",+ "testing",+ "vitest",+ "tdd",+ "london-school",+ "mocks",+ "fixtures"+ ],+ "peerDependencies": {+ "vitest": ">=1.0.0"},"devDependencies": {"vitest": "^1.0.0"