feat: comprehensive MockAgent debugging improvements

[mcollina]

Summary

This PR implements comprehensive debugging improvements for MockAgent to address the common pain point of difficult debugging when mocks don't match requests. The changes provide detailed context, intelligent suggestions, and powerful state inspection tools.

🚀 Key Features

Enhanced Error Messages

• Rich context: MockNotMatchedError now includes available interceptors table, request details, and potential matches
• Smart suggestions: Similarity-based matching recommendations when requests fail
• Actionable feedback: Clear indication of why requests don't match specific interceptors

Real-time Request Tracing

• Basic mode (traceRequests: true): Simple match/no-match with interceptor suggestions
• Verbose mode (traceRequests: 'verbose'): Detailed step-by-step matching process
• Console output: All tracing goes to console.error for easy debugging

Development Mode

• Auto-configuration: developmentMode: true automatically enables debugging features
• Zero-config debugging: Call history, tracing, and verbose errors enabled by default

State Inspection Tools

• debug(): Returns comprehensive MockAgent state as structured data
• inspect(): Pretty-prints debug information to console with tables
• compareRequest(): Detailed diff analysis between requests and interceptors

Interceptor Validation

• validate(): Proactive validation of interceptor configuration
• Issue detection: Identifies common problems like double slashes, unusual methods, conflicting settings
• Severity levels: Distinguishes between warnings and errors

Enhanced Assertions

• Extended assertNoPendingInterceptors() with new options:
  • showUnusedInterceptors: Display interceptors that were never called
  • showCallHistory: Include recent request history in error messages
  • includeRequestDiff: Show detailed comparison between recent requests and pending interceptors

📊 Usage Examples

// Development mode - auto-enables all debugging features
const mockAgent = new MockAgent({ developmentMode: true })

// Real-time request tracing
const mockAgent = new MockAgent({ traceRequests: 'verbose' })

// State inspection
mockAgent.inspect() // Pretty console output
const state = mockAgent.debug() // Structured data

// Interceptor validation
const scope = mockPool.intercept({ path: '/api', method: 'GET' }).reply(200, {})
const validation = scope.validate()

// Request analysis
const diff = mockAgent.compareRequest(request, interceptor)

// Enhanced error reporting
mockAgent.assertNoPendingInterceptors({
  showUnusedInterceptors: true,
  showCallHistory: true,
  includeRequestDiff: true
})

🔧 Technical Details

• Backward compatible: All changes are opt-in and don't affect existing functionality
• TypeScript support: Complete type definitions for all new methods and options
• Performance: Debugging features only activate when explicitly enabled
• Testing: Comprehensive test suite with 11 test cases covering all features
• Code quality: Passes all linting checks and follows existing patterns

📈 Before/After

Before:

MockNotMatchedError: Mock dispatch not matched for path '/api/users'

After:

Mock dispatch not matched for path '/api/users'

Available interceptors for origin 'http://localhost:3000':
┌─────────┬────────┬─────────────┬─────────────┬────────────┐
│ Method  │ Path   │ Status      │ Persistent  │ Remaining  │
├─────────┼────────┼─────────────┼─────────────┼────────────┤
│ GET     │ /api/  │ 200         │ ❌          │ 1          │
│ POST    │ /users │ 201         │ ✅          │ ∞          │
└─────────┴────────┴─────────────┴─────────────┴────────────┘

Request details:
- Method: GET
- Path: /api/users
- Headers: {"content-type": "application/json"}
- Body: undefined

Potential matches:
- GET /api (path mismatch, similarity: 0.7)
- POST /users (method mismatch)

🧪 Test Plan

• All existing MockAgent tests continue to pass
• New debugging features work in isolation
• Development mode enables features correctly
• Request tracing outputs expected console messages
• Enhanced error messages include proper context
• Interceptor validation detects common issues
• TypeScript definitions are complete and accurate
• Performance impact is minimal when features disabled

🔗 Related

Addresses the MockAgent debugging challenges outlined in the planning document. This implementation follows the prioritized feature list and maintains full backward compatibility while dramatically improving the debugging experience.

🤖 Generated with Claude Code