Skip to documentation

Guide · Realtime

Limited

Mock connections and timelines, not just request-response pairs

DotMock combines OpenAPI 3.2 SSE operations, AsyncAPI 3.0 WebSocket channels, ordered declarative scenarios, and seed-replayable connection traffic.

UTF-8 text and JSON workflows are available. Binary WebSocket application messages are rejected with close code 1003.

In this guide

  • Attach streams to REST or create a realtime-only workspace
  • Author SSE and WebSocket contracts
  • Test rooms with multiple virtual clients
  • Inspect, replay, and promote captured sessions

Prerequisites

  • A DotMock workspace you can access
  • The API ID in $API_ID and its published runtime URL in $MOCK_URL when the example calls the mock
On this page
  1. Keep each transport in its native contract
  2. Use deterministic connection scenarios
  3. Connect browser-native clients safely
  4. Resume and replay the exact connection
  5. Inspect bounded mock and proxy sessions

Keep each transport in its native contract

Describe SSE in OpenAPI 3.2 with a text/event-stream response and itemSchema. Describe each WebSocket connection path as one AsyncAPI channel using the WebSocket binding. AsyncAPI send is DotMock-to-client; receive is client-to-DotMock.

yaml
# OpenAPI SSE
text/event-stream:
  itemSchema:
    type: object

# AsyncAPI operation
action: send
channel:
  $ref: '#/channels/chat'

Use deterministic connection scenarios

Order connect, message, timer, and disconnect triggers by stable rank. Compose send, join, leave, broadcast, state, and close actions. Rooms stay ephemeral runtime routing metadata instead of becoming fake contract channels.

Connect browser-native clients safely

EventSource and browser WebSocket cannot set x-api-key headers. Issue a five-minute target-scoped connection URL. DotMock validates and strips _dotmock_token before matching, proxying, or logging.

bash
dotmock realtime sse --api "$API_ID" --target events --path /events --seed replay-42
dotmock realtime ws --api "$API_ID" --target chat --path /chat --clients 2 --subprotocol chat.v1

Resume and replay the exact connection

SSE targets choose strict, restart, or latest behavior for unknown Last-Event-ID values. Every connection records a seed; pass it to the UI tester, CLI, or MCP tools to reproduce seeded decisions without affecting live state during dry runs.

Inspect bounded mock and proxy sessions

Connection traffic records handshake metadata, relative timing, direction, payload, matched scenario, room activity, source, seed, close source, duration, and metering. Timelines cap at 500 entries or 1 MiB and mark truncation.

bash
dotmock --json realtime traffic --api "$API_ID"
dotmock --json realtime usage --api "$API_ID"
dotmock realtime promote --api "$API_ID" --traffic "$SESSION_ID" --target chat --from actions.yaml --yes