Claude-Code-Workflow/ccw/tests/e2e/QUICK_START.md

E2E Tests Quick Start Guide

Run All E2E Tests

npm run test:e2e

Run Individual Test Suites

Session Lifecycle Tests

node --experimental-strip-types --test ccw/tests/e2e/session-lifecycle.e2e.test.ts

Tests: 10 test cases covering full session workflow from init to archive

Dashboard WebSocket Tests

node --experimental-strip-types --test ccw/tests/e2e/dashboard-websocket.e2e.test.ts

Tests: 8 test cases covering real-time updates and fire-and-forget notifications

MCP Tools Tests

node --experimental-strip-types --test ccw/tests/e2e/mcp-tools.e2e.test.ts

Tests: 14 test cases covering JSON-RPC tool execution and validation

Run with Verbose Output

node --experimental-strip-types --test --test-reporter=spec ccw/tests/e2e/*.e2e.test.ts

Expected Output

✔ E2E: Session Lifecycle (Golden Path)
  ✔ completes full session lifecycle: init → add tasks → update status → archive (152ms)
  ✔ supports dual parameter format: legacy (operation) and new (explicit params) (45ms)
  ✔ handles boundary condition: invalid JSON in task file (38ms)
  ✔ handles boundary condition: non-existent session (12ms)
  ✔ handles boundary condition: path traversal attempt (25ms)
  ✔ handles concurrent task updates without data loss (89ms)
  ✔ preserves task data when archiving session (67ms)
  ✔ lists sessions across all locations (112ms)

✔ E2E: Dashboard WebSocket Live Updates
  ✔ broadcasts SESSION_CREATED event when session is initialized (234ms)
  ✔ broadcasts TASK_UPDATED event when task status changes (198ms)
  ✔ broadcasts SESSION_ARCHIVED event when session is archived (187ms)
  ✔ handles multiple WebSocket clients simultaneously (412ms)
  ✔ handles fire-and-forget notification behavior (no blocking) (89ms)
  ✔ handles network failure gracefully (no dashboard crash) (156ms)
  ✔ validates event payload structure (178ms)
  ✔ handles WebSocket reconnection after disconnect (267ms)

✔ E2E: MCP Tool Execution
  ✔ lists available tools via tools/list (567ms)
  ✔ executes smart_search tool with valid parameters (234ms)
  ✔ validates required parameters and returns error for missing params (123ms)
  ✔ returns error for non-existent tool (98ms)
  ✔ executes session_manager tool for session operations (456ms)
  ✔ handles invalid JSON in tool arguments gracefully (87ms)
  ✔ executes write_file tool with proper parameters (145ms)
  ✔ executes edit_file tool with update mode (178ms)
  ✔ handles concurrent tool calls without interference (389ms)
  ✔ validates path parameters for security (path traversal prevention) (112ms)
  ✔ supports progress reporting for long-running operations (203ms)
  ✔ handles tool execution timeout gracefully (89ms)
  ✔ returns consistent error format across different error types (156ms)
  ✔ preserves parameter types in tool execution (134ms)

✔ 32 tests passed (8.5s)

Troubleshooting

Tests Timeout

If tests timeout, increase timeout values:

// In test file
const timeout = setTimeout(() => reject(new Error('Timeout')), 10000); // Increase from 5000

Port Conflicts

Tests use random ports, but if conflicts occur:

# Kill existing processes
pkill -f ccw-mcp
pkill -f "node.*test"

Temp Directory Cleanup

If tests fail and leave temp directories:

# Linux/Mac
rm -rf /tmp/ccw-e2e-*

# Windows
del /s /q %TEMP%\ccw-e2e-*

MCP Server Won't Start

Ensure ccw-mcp.js is executable:

# Check if built
ls -la ccw/bin/ccw-mcp.js

# Rebuild if needed
npm run build

Prerequisites

• Node.js: >= 16.0.0 (for --experimental-strip-types)
• TypeScript: Installed (for build)
• Build Status: Run npm run build first

Quick Verification

Test that everything is working:

# 1. Build project
npm run build

# 2. Run one quick test
node --experimental-strip-types --test ccw/tests/e2e/session-lifecycle.e2e.test.ts --test-only --grep "supports dual parameter format"

# 3. If successful, run all E2E tests
npm run test:e2e

Test Coverage Summary

Test Suite	Test Cases	Coverage
Session Lifecycle	10	Golden path + boundaries
Dashboard WebSocket	8	Real-time events
MCP Tools	14	JSON-RPC protocol
Total	32	High

Next Steps

After running tests:

1. Check output for any failures
2. Review ccw/tests/e2e/README.md for detailed documentation
3. Review ccw/tests/e2e/IMPLEMENTATION_SUMMARY.md for technical details
4. Add new test cases following existing patterns

Common Test Patterns

Adding a New Test Case

it('describes what this test does', async () => {
  // Arrange: Set up test data
  const sessionId = 'WFS-test-new';

  // Act: Execute the operation
  const result = await sessionManager.handler({
    operation: 'init',
    session_id: sessionId,
    metadata: { type: 'workflow' }
  });

  // Assert: Verify results
  assert.equal(result.success, true);
  assert.ok(result.result.path);
});

Boundary Condition Test Template

it('handles edge case: [describe edge case]', async () => {
  // Arrange: Create invalid/edge case scenario

  // Act: Execute operation that should handle it
  const result = await handler({ /* invalid data */ });

  // Assert: Verify graceful handling
  assert.equal(result.success, false);
  assert.ok(result.error.includes('expected error message'));
});

Support

For issues or questions:

• Review test documentation in ccw/tests/e2e/README.md
• Check existing test patterns in test files
• Ensure all prerequisites are met
• Verify npm run build completes successfully

---

Happy Testing! 🧪