WebSocket API

The LiveDoc Viewer uses WebSocket connections to push test results to the browser in real time. This page documents the WebSocket endpoint, message format, and available event types.

---

Connecting

Connect to the /ws path on the viewer's host and port:

ws://localhost:3100/ws

The server accepts standard WebSocket connections. All messages are JSON-encoded strings.

JavaScript Example

const ws = new WebSocket('ws://localhost:3100/ws');

ws.onopen = () => {
  console.log('Connected to LiveDoc Viewer');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log(`Event: ${message.type}`, message.payload);
};

ws.onclose = () => {
  console.log('Disconnected from LiveDoc Viewer');
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

Node.js Example

import WebSocket from 'ws';

const ws = new WebSocket('ws://localhost:3100/ws');

ws.on('open', () => {
  console.log('Connected');
});

ws.on('message', (data) => {
  const message = JSON.parse(data.toString());
  console.log(`${message.type}:`, message.payload);
});

---

Message Format

Every WebSocket message follows this structure:

interface WebSocketMessage {
  type: string;      // Event type identifier
  payload: unknown;  // Event-specific data
}

{
  "type": "run:started",
  "payload": {
    "runId": "run-004",
    "project": "my-api",
    "environment": "local",
    "startedAt": "2025-01-15T10:30:00Z"
  }
}

---

Event Types

run:started

Emitted when a new test run begins.

{
  "type": "run:started",
  "payload": {
    "runId": "run-004",
    "project": "my-api",
    "environment": "local",
    "startedAt": "2025-01-15T10:30:00Z"
  }
}

---

run:completed

Emitted when a test run finishes (all features/scenarios done).

{
  "type": "run:completed",
  "payload": {
    "runId": "run-004",
    "completedAt": "2025-01-15T10:30:45Z",
    "summary": {
      "features": 5,
      "scenarios": 23,
      "passed": 22,
      "failed": 1,
      "skipped": 0,
      "duration": 45000
    }
  }
}

---

scenario:completed

Emitted when a single scenario (or rule) finishes execution.

{
  "type": "scenario:completed",
  "payload": {
    "runId": "run-004",
    "feature": "User Authentication",
    "scenario": "Successful login",
    "status": "passed",
    "steps": [
      {
        "keyword": "Given",
        "title": "a registered user",
        "status": "passed",
        "duration": 12
      },
      {
        "keyword": "When",
        "title": "the user submits valid credentials",
        "status": "passed",
        "duration": 25
      },
      {
        "keyword": "Then",
        "title": "the user is logged in",
        "status": "passed",
        "duration": 8
      }
    ],
    "duration": 45
  }
}

---

step:completed

Emitted when an individual step finishes. This provides the most granular real-time feedback.

{
  "type": "step:completed",
  "payload": {
    "runId": "run-004",
    "feature": "User Authentication",
    "scenario": "Successful login",
    "step": {
      "keyword": "Given",
      "title": "a registered user",
      "status": "passed",
      "duration": 12
    }
  }
}

---

Event Flow

A typical test run produces events in this order:

1. The test reporter calls POST /api/runs/start to begin a streaming run
2. As each step completes, the viewer broadcasts step:completed to all connected clients
3. After all steps in a scenario finish, scenario:completed is broadcast
4. When the entire run is done, run:completed is broadcast with the summary

---

Connection Handling

Auto-Reconnection

The viewer's built-in web UI automatically reconnects if the WebSocket connection drops. If you're building a custom client, implement reconnection with exponential backoff:

function connect() {
  const ws = new WebSocket('ws://localhost:3100/ws');

  ws.onclose = () => {
    // Reconnect after 2 seconds
    setTimeout(connect, 2000);
  };

  ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    handleEvent(message);
  };
}

connect();

Multiple Clients

The viewer supports multiple simultaneous WebSocket connections. All connected clients receive the same events. This means you can have the browser dashboard open alongside a custom monitoring script.

---

Quick Reference

Event	When it fires	Key payload fields
run:started	A new test run begins	runId, project, environment
run:completed	A test run finishes	runId, summary (pass/fail counts)
scenario:completed	A scenario/rule finishes	runId, feature, scenario, steps
step:completed	An individual step finishes	runId, feature, scenario, step

---

See Also

• REST API — query and manage runs via HTTP
• CLI Options — configure the server host and port
• Getting Started — initial setup walkthrough