ruvnet--ruflo/v3/@claude-flow/cli/__tests__/README.md

CLI Module Tests

This directory contains comprehensive tests for the V3 CLI module using Vitest.

Test Files

1. cli.test.ts (~15+ tests)

Tests for the main CLI class covering:

• Version command (--version, -V)
• Help output (--help, -h)
• Command parsing (long flags, short flags, equals syntax)
• Positional arguments
• Boolean flags and negation
• Global flags (--quiet, --format, --config, --no-color)
• Error handling (unknown commands, missing options)
• Subcommand execution and aliases
• Exit codes

2. mcp-client.test.ts (~10+ tests)

Tests for MCP tool invocation:

• callMCPTool() - Tool execution with various inputs
• getToolMetadata() - Metadata retrieval
• listMCPTools() - Tool listing and filtering by category
• hasTool() - Tool existence checks
• getToolCategories() - Category enumeration
• validateToolInput() - Input validation against schemas
• MCPClientError - Custom error handling

3. commands.test.ts (~48+ tests)

Tests for all CLI commands:

Agent Commands (spawn, list, status, stop, metrics):

• Spawning agents with various configurations
• Listing agents with filters
• Getting agent status and metrics
• Stopping agents (graceful/force)
• Agent performance metrics

Swarm Commands (init, start, status, stop, scale, coordinate):

• Initializing swarms with different topologies
• Starting swarm execution with objectives
• Checking swarm status
• Stopping and scaling swarms
• V3 15-agent coordination structure

Memory Commands (store, retrieve, search, list, delete, stats, configure):

• Storing data in memory (with/without vectors)
• Retrieving data by key
• Semantic/vector search
• Listing memory entries
• Deleting entries
• Viewing statistics
• Backend configuration

Config Commands (init, get, set, providers, reset, export, import):

• Initializing configuration
• Getting/setting config values
• Managing AI providers
• Resetting to defaults
• Exporting/importing configuration

Mocking Strategy

MCP Tools

All MCP tools are mocked at the module level to prevent actual tool execution:

• agent-tools.js - Mocked agent operations
• swarm-tools.js - Mocked swarm coordination
• memory-tools.js - Mocked memory operations
• config-tools.js - Mocked configuration

Output

The output module is fully mocked to capture formatted output without console pollution.

Prompts

Interactive prompts (select, confirm, input, multiSelect) are mocked to return default values for non-interactive testing.

Process

process.exit() is mocked to throw errors instead of terminating the test process.

Running Tests

# Run all CLI tests
npm test -- v3/@claude-flow/cli/__tests__/

# Run specific test file
npm test -- v3/@claude-flow/cli/__tests__/cli.test.ts

# Run with coverage
npm test -- v3/@claude-flow/cli/__tests__/ --coverage

# Run in watch mode
npm test -- v3/@claude-flow/cli/__tests__/ --watch

Test Coverage Goals

• Statements: >80%
• Branches: >75%
• Functions: >80%
• Lines: >80%

Key Testing Patterns

1. Command Execution

const result = await command.action!(ctx);
expect(result.success).toBe(true);
expect(result.data).toHaveProperty('expectedField');

2. Flag Parsing

ctx.flags = { myFlag: 'value', _: [] };
await command.action!(ctx);
// Assertions in action callback

3. Error Handling

try {
  await cli.run(['invalid-command']);
} catch (e) {
  expect((e as Error).message).toContain('process.exit');
}

4. Output Validation

const output = consoleOutput.join('');
expect(output).toContain('Expected text');

Notes

• All tests are non-interactive (interactive: false)
• Console output is captured for verification
• Process exits are converted to exceptions
• MCP client is fully isolated from actual MCP server
• Tests use unique command names to avoid conflicts