@ebowwa/claude-code-mcp 1.0.0 → 1.0.2

package/TESTING.md

@@ -1,318 +0,0 @@
-# Testing Guide
-
-This document describes how to run and extend tests for the `@mcp/claude-code` MCP server.
-
-## Test Structure
-
-```
-src/
-├── cli-wrapper.test.ts     # Unit tests for CLI wrapper and Doppler integration
-├── integration.test.ts     # Integration tests with mock Claude binary
-└── test-config.ts          # Shared test utilities and mock helpers
-```
-
-## Running Tests
-
-### Run All Tests
-
-```bash
-bun test
-```
-
-### Run Specific Test Suites
-
-```bash
-# CLI wrapper tests only
-bun run test:cli-wrapper
-
-# Integration tests only
-bun run test:integration
-```
-
-### Watch Mode
-
-```bash
-bun run test:watch
-```
-
-## Test Files
-
-### cli-wrapper.test.ts
-
-Unit tests for the `ClaudeCodeWrapper` class:
-
-- **Constructor tests**: Default options, custom options
-- **Spawn tests**: Process spawning with/without Doppler
-- **Kill tests**: Graceful and force termination
-- **isAlive tests**: Process state tracking
-- **Doppler integration**: --resume flag handling, command construction
-- **Error handling**: Spawn failures, kill failures
-- **Edge cases**: Malformed UUIDs, missing environment variables, message escaping
-
-**Key test cases:**
-- Doppler workaround for `--resume` flag
-- Rolling API keys with Doppler
-- Special character escaping in messages
-- Process lifecycle management
-
-### integration.test.ts
-
-Integration tests with a mock Claude binary:
-
-- **start_session**: Starting new sessions with project context
-- **resume_session**: Resuming sessions with Doppler wrapper
-- **list_sessions**: Listing and filtering sessions
-- **kill_session**: Terminating running sessions
-- **send_message**: Sending messages to active sessions
-- **sync_context**: Context synchronization between sessions
-- **stream_output**: Output streaming from sessions
-- **wait_for_completion**: Waiting for session completion with timeout
-
-**Key test cases:**
-- Full tool call lifecycle
-- Session state management
-- Doppler integration simulation
-- Error handling for invalid inputs
-
-### test-config.ts
-
-Shared utilities:
-
-- `TEST_CONFIG`: Test environment configuration
-- `MOCK_SESSIONS`: Mock session data for tests
-- `DOPPLER_TEST_CONFIGS`: Doppler test configurations
-- `MOCK_API_KEYS`: Mock API key data
-- `setupTestEnvironment()`: Create test directories
-- `cleanupTestEnvironment()`: Remove test artifacts
-- `createMockClaudeBinary()`: Create mock Claude executable
-- `createMockDoppler()`: Create mock doppler CLI
-- `MockMCPServer`: Mock server class for testing
-- `expect`: Assertion helpers
-- `wait`, `retry`, `time`: Async test utilities
-
-## Test Patterns
-
-### Pattern 1: Testing with Mock Binary
-
-```typescript
-import { createMockClaudeBinary } from './test-config';
-
-describe('My Feature', () => {
-  let mockPath: string;
-
-  beforeEach(async () => {
-    mockPath = await createMockClaudeBinary();
-  });
-
-  afterEach(async () => {
-    // Cleanup
-  });
-
-  it('should work with mock Claude', async () => {
-    const process = Bun.spawn([mockPath, '--version']);
-    // Test logic...
-  });
-});
-```
-
-### Pattern 2: Testing Doppler Integration
-
-```typescript
-describe('Doppler Integration', () => {
-  it('should construct correct command', () => {
-    const wrapper = new ClaudeCodeWrapper({ useDoppler: true });
-    const cmd = wrapper.buildResumeCommand('uuid-123');
-    expect(cmd).toContain('--resume');
-    expect(cmd).toContain('doppler');
-  });
-});
-```
-
-### Pattern 3: Testing MCP Tool Calls
-
-```typescript
-describe('MCP Tool', () => {
-  let server: MockMCPServer;
-
-  beforeEach(() => {
-    server = new MockMCPServer();
-    server.registerTool('my_tool', async function(args: any) {
-      // Tool implementation
-    });
-  });
-
-  it('should call tool correctly', async () => {
-    const result = await server.callTool('my_tool', { param: 'value' });
-    expect.success(result);
-  });
-});
-```
-
-## Edge Cases Tested
-
-### Doppler Flag Handling
-
-1. **Valid UUID with --resume**
-   - Standard UUID format: `abc-123-def-456`
-   - Command construction: `doppler run --command "claude --resume UUID"`
-
-2. **Malformed UUIDs**
-   - Empty string
-   - Non-UUID strings
-   - Special characters
-   - Should construct command anyway (validation at Claude level)
-
-3. **Missing Doppler Configuration**
-   - No `DOPPLER_PROJECT` set
-   - No `DOPPLER_CONFIG` set
-   - Empty `DOPPLER_TOKEN`
-   - Should still construct doppler command
-
-4. **Message Escaping**
-   - Quotes in message: `Fix the "auth" bug` → `Fix the \"auth\" bug`
-   - Newlines in message: `Line 1\nLine 2` → `Line 1\\nLine 2`
-   - Empty messages
-
-### Process Lifecycle
-
-1. **Spawn-Kill Cycles**
-   - Single spawn/kill
-   - Rapid spawn-kill cycles
-   - Multiple kills (should be idempotent)
-
-2. **State Tracking**
-   - Idle → Running → Killed
-   - Process ID tracking
-   - Alive status checks
-
-### Session Management
-
-1. **Invalid Session IDs**
-   - Non-existent sessions
-   - Malformed UUIDs
-   - Empty strings
-
-2. **Status Filtering**
-   - Active sessions only
-   - Completed sessions only
-   - All sessions
-
-3. **Context Sync**
-   - Sync all context types
-   - Sync specific types (history, files, state)
-   - Direct context application
-
-## CI/CD Integration
-
-### GitHub Actions Example
-
-```yaml
-name: Tests
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: oven-sh/setup-bun@v1
-        with:
-          bun-version: latest
-      - run: bun install
-      - run: bun test
-```
-
-## Writing New Tests
-
-1. **Choose the right file:**
-   - Unit tests for a class → `cli-wrapper.test.ts`
-   - Integration tests for tools → `integration.test.ts`
-   - Shared utilities → `test-config.ts`
-
-2. **Follow the pattern:**
-   ```typescript
-   describe('Feature Name', () => {
-     beforeEach(() => {
-       // Setup
-     });
-
-     afterEach(() => {
-       // Cleanup
-     });
-
-     it('should do something expected', async () => {
-       // Arrange
-       const input = { ... };
-
-       // Act
-       const result = await functionUnderTest(input);
-
-       // Assert
-       expect(result).toBe(expected);
-     });
-   });
-   ```
-
-3. **Use the helpers:**
-   - `expect.success(result)` - Assert MCP call succeeded
-   - `expect.error(result, 'message')` - Assert MCP call failed with message
-   - `await setupTestEnvironment()` - Create test directories
-   - `await cleanupTestEnvironment()` - Remove test artifacts
-
-4. **Test edge cases:**
-   - Invalid inputs
-   - Missing required fields
-   - Empty strings/arrays
-   - Malformed data
-   - Race conditions
-
-## Debugging Tests
-
-### Run Tests with Verbose Output
-
-```bash
-bun test --verbose
-```
-
-### Run Specific Test
-
-```bash
-bun test src/cli-wrapper.test.ts -t "should spawn Claude Code without Doppler"
-```
-
-### Debug with Console Logs
-
-```typescript
-it('should do something', () => {
-  console.log('Debug info:', someVariable);
-  // Test logic...
-});
-```
-
-## Coverage
-
-To generate coverage reports (when bun test --coverage is available):
-
-```bash
-bun run test:coverage
-```
-
-## Troubleshooting
-
-### "Mock binary not found"
-
-- Ensure `createMockClaudeBinary()` is called in `beforeEach`
-- Check that the mock path is correct
-
-### "Test timeout"
-
-- Increase timeout in test config
-- Check for hanging promises
-- Ensure proper cleanup in `afterEach`
-
-### "Doppler tests failing"
-
-- Ensure doppler is mocked (not calling real doppler)
-- Check environment variable handling
-- Verify command construction logic