Skip to content

feat: add mock websocket requests#35

Open
cryptotavares wants to merge 10 commits into
mainfrom
cryptotavares/add-mock-websocket-requests
Open

feat: add mock websocket requests#35
cryptotavares wants to merge 10 commits into
mainfrom
cryptotavares/add-mock-websocket-requests

Conversation

@cryptotavares

@cryptotavares cryptotavares commented Jun 3, 2026

Copy link
Copy Markdown
Collaborator

Summary

The existing mock_network tool only intercepts HTTP requests. WebSocket connections — used heavily by dApps for real-time data (price feeds, order books, streaming state) — pass through unintercepted. This makes it impossible to test WebSocket-dependent flows without a live server, or to simulate specific server-to-client message sequences.

This PR adds a mock_websocket tool that intercepts WebSocket connections via Playwright's routeWebSocket API, enabling targeted message matching, scripted responses, and full connection lifecycle control.

Changes

New tool: mock_websocket

Mirrors the mock_network tool's action-based API (add, clear, list, messages) adapted for WebSocket semantics:

  • Intercepts by exact URL — each mock targets a specific ws:// or wss:// endpoint (no wildcards, since WebSocket routing in Playwright uses exact URL matching)
  • Rule-based message matching — incoming messages are matched against rules using substring inclusion (includes: string | string[]). Matched messages trigger scripted respond and/or followUpResponse payloads with optional delays
  • Two connection modes: passthrough (default) connects to the real server and forwards unmatched messages; full mock mode (passthrough: false) operates without a real connection
  • Connection lifecycle management — tracks active connections per URL; replacing a mock for the same URL closes stale connections and invalidates pending delayed responses via a generation counter
  • Message recording — records all intercepted messages (client-to-server and server-to-client) with direction, timestamps, and matched rule IDs; capped at 500 records with configurable truncation

Architecture

Layer Files What
Types tool-inputs.ts, tool-outputs.ts, errors.ts WebSocketMockDefinition, WebSocketMockMessageRule, MockWebSocketInput/Result, MM_MOCK_WEBSOCKET_FAILED error code
Validation schemas.ts Zod schemas with URL protocol enforcement (ws:///wss:// only), wildcard rejection, exclusive mock/mocks constraint on add action
Core mock-websocket.ts WebSocketMockRouteManager class (per-BrowserContext via WeakMap) and mockWebSocketTool entry point
Registry registry.ts Registered as mock_websocket, categorized as mutating (tool count: 30 → 31)
CLI mm.ts mm mock-websocket {add,clear,list,messages} subcommands
Docs README.md, SKILL.md Tool table, CLI reference, error codes

Other changes

  • mock-network tests: improved type narrowing in result assertions (replacing broad type checks with discriminated union narrowing via result.action)
  • Coverage thresholds: adjusted branches, functions, and statements thresholds in vitest.config.mts to reflect the new code

Testing

Comprehensive test suite in mock-websocket.test.ts covering:

  • All four actions (add/clear/list/messages)
  • Full mock mode and passthrough mode
  • Delayed responses and follow-up responses with timer ordering
  • Mock replacement with socket closure and generation invalidation
  • Stale timer cancellation across clear and replace scenarios
  • Active connection tracking (including no-negative-count after clear)
  • Message record retention limits
  • Error handling for closed connections
  • Schema validation tests for URL enforcement, wildcard rejection, and exclusive mock/mocks constraint

@cryptotavares cryptotavares requested a review from a team as a code owner June 3, 2026 10:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant