WebSocket Protocol Guide
Use this guide when long-lived WebSocket sessions, message matching, or realtime channels need to be part of a performance or transaction test.
Matching docs
Search across docs titles, summaries, groups, and section headings.
Use Up and Down Arrow to move through results, then press Enter to open the active page.
No indexed docs matched that search. Try a broader term or open the docs hub.
What this page helps you do
What this page helps you do
Use this guide when long-lived WebSocket sessions, message matching, or realtime channels need to be part of a performance or transaction test.
Who this is for
Teams deciding how a protocol or browser runtime should fit inside one transaction-aware scenario.
Prerequisites
- A transport or browser flow that already matters to the workload
By the end
A clearer protocol-specific path that still fits the same scenario and reporting model.
Use this page when
Use this page when WebSocket Protocol Guide belongs inside the transaction story and you need the supported path into the same scenario model.
Visual guide
Guide
What This Guide Covers
Use this guide when a WebSocket connection is the source, destination, or observed channel in the workflow. LoadStrike supports ws:// and wss:// endpoint configuration, subprotocols, headers, connect and close timeouts, text and binary message specifications, expected-message matching, reconnect policy, message latency, throughput, and byte metrics where supported by the SDK.
Long-Lived Sessions
WebSocket scenarios often care about more than one request. Model the connect, send, receive, and close behavior explicitly so reports can show message latency, connection duration, reconnects, receive timeouts, and protocol failures beside normal scenario counts.
Exact SDK Support
C#, Java, Python, TypeScript, JavaScript, and Go support native or delegate-backed Produce and Consume. Python native use requires the websocket install extra, and TypeScript or JavaScript native use runs on Node.js. A matching delegate takes precedence over NativeClient.
Native Limits And Compatibility
Native Consume uses JSON tracking because WebSocket frames do not include application message headers. Java limits a fully reassembled inbound text or binary message to 1 MiB. Java TrackPingPong, TrackCloseCodes, and TrackMessageLatency are deprecated compatibility fields with no effect.
Plan Gate
WebSocket endpoint support is available on Pro and above. Runs still validate any extra features used by the scenario, such as portal reporting, sinks, thresholds, or distributed cluster settings.
Protocol setup samples
Use these samples for native or delegate-backed WebSocket Produce and Consume in C#, Java, Python, TypeScript, JavaScript, and Go. A matching mode delegate takes precedence over NativeClient. Python native WebSocket use requires the websocket extra.
If you run these examples locally, add a valid runner key before execution starts. Set it with WithRunnerKey("...") or the config key LoadStrike:RunnerKey.
WebSocket Protocol Setup
using LoadStrike;
using LoadStrike.CrossPlatform;
using LoadStrike.CrossPlatform.WebSockets;
// NativeClient is available for C# Produce and Consume endpoints.
var endpoint = new WebSocketEndpointDefinition
{
Name = "orders-websocket",
Mode = TrafficEndpointMode.Produce,
TrackingField = TrackingFieldSelector.Parse("header:x-tracking-id"),
Url = "wss://realtime.example.com/orders",
Subprotocols = ["orders.v1"],
MessageHeaders = new Dictionary<string, string>
{
["x-tracking-id"] = "ord-1001"
},
NativeClient = new WebSocketNativeClientOptions
{
Messages =
[
WebSocketMessageSpec.Text("{\"type\":\"subscribe\",\"orderId\":\"ord-1001\"}")
],
ExpectedMessages =
[
new WebSocketExpectedMessage
{
ContainsText = "ord-1001",
Timeout = TimeSpan.FromSeconds(10)
}
]
}
};
_ = endpoint;package main
import loadstrike "loadstrike.com/sdk/go"
// NativeClient works for Produce and Consume.
var webSocketEndpoint = &loadstrike.EndpointSpec{
Kind: "WebSocket",
Name: "orders-websocket",
Mode: "Consume",
TrackingField: "json:$.trackingId",
WebSocket: &loadstrike.WebSocketEndpointOptions{
URL: "wss://realtime.example.com/orders",
Subprotocols: []string{"orders.v1"},
NativeClient: &loadstrike.WebSocketNativeClientOptions{
Messages: []loadstrike.WebSocketMessageSpec{
loadstrike.TextWebSocketMessage(`{"type":"subscribe","trackingId":"ord-1001"}`),
},
ExpectedMessages: []loadstrike.WebSocketExpectedMessage{
{MatchText: "ord-1001", TimeoutSeconds: 10},
},
},
},
}import java.time.Duration;
import com.loadstrike.runtime.LoadStrikeCorrelation.TrackingFieldSelector;
import com.loadstrike.runtime.LoadStrikeTransports;
import com.loadstrike.runtime.WebSocketEndpointDefinition;
import com.loadstrike.runtime.WebSocketEndpointDefinition.ExpectedMessage;
import com.loadstrike.runtime.WebSocketEndpointDefinition.MessageSpec;
import com.loadstrike.runtime.WebSocketEndpointDefinition.NativeClientOptions;
// Java supports native WebSocket Produce and Consume.
var endpoint = new WebSocketEndpointDefinition();
endpoint.name = "orders-websocket";
endpoint.mode = LoadStrikeTransports.TrafficEndpointMode.Consume;
endpoint.trackingField = TrackingFieldSelector.parse("json:$.trackingId");
endpoint.url = "wss://realtime.example.com/orders";
endpoint.subprotocols = java.util.List.of("orders.v1");
var nativeClient = new NativeClientOptions();
nativeClient.messages.add(
MessageSpec.Text(
"{\"type\":\"subscribe\",\"trackingId\":\"ord-1001\"}"));
nativeClient.expectedMessages.add(
new ExpectedMessage(
"ord-1001", null, Duration.ofSeconds(10)));
endpoint.nativeClient = nativeClient;from loadstrike_sdk import (
WebSocketEndpointDefinition,
WebSocketExpectedMessage,
WebSocketMessageSpec,
WebSocketNativeClientOptions,
)
# Install with: pip install "loadstrike[websocket]"
endpoint = WebSocketEndpointDefinition(
name="orders-websocket",
mode="Consume",
tracking_field="json:$.trackingId",
url="wss://realtime.example.com/orders",
subprotocols=["orders.v1"],
native_client=WebSocketNativeClientOptions(
messages=[
WebSocketMessageSpec.Text(
'{"type":"subscribe","trackingId":"ord-1001"}'
)
],
expected_messages=[
WebSocketExpectedMessage(contains_text="ord-1001", timeout_seconds=10)
],
),
)import {
WebSocketEndpointDefinition,
WebSocketExpectedMessage,
WebSocketMessageSpec,
WebSocketNativeClientOptions
} from "@loadstrike/loadstrike-sdk";
// NativeClient works for Produce and Consume on Node.js.
const endpoint = new WebSocketEndpointDefinition({
Name: "orders-websocket",
Mode: "Consume",
TrackingField: "json:$.trackingId",
Url: "wss://realtime.example.com/orders",
Subprotocols: ["orders.v1"],
NativeClient: new WebSocketNativeClientOptions({
Messages: [WebSocketMessageSpec.Text('{"type":"subscribe","trackingId":"ord-1001"}')],
ExpectedMessages: [new WebSocketExpectedMessage({
ContainsText: "ord-1001",
TimeoutSeconds: 10
})]
})
});
void endpoint;const {
WebSocketEndpointDefinition,
WebSocketExpectedMessage,
WebSocketMessageSpec,
WebSocketNativeClientOptions
} = require("@loadstrike/loadstrike-sdk");
// NativeClient works for Produce and Consume on Node.js.
const endpoint = new WebSocketEndpointDefinition({
Name: "orders-websocket",
Mode: "Consume",
TrackingField: "json:$.trackingId",
Url: "wss://realtime.example.com/orders",
Subprotocols: ["orders.v1"],
NativeClient: new WebSocketNativeClientOptions({
Messages: [WebSocketMessageSpec.Text('{"type":"subscribe","trackingId":"ord-1001"}')],
ExpectedMessages: [new WebSocketExpectedMessage({
ContainsText: "ord-1001",
TimeoutSeconds: 10
})]
})
});
void endpoint;Goal
Use an absolute ws:// or wss:// endpoint for the realtime channel under test.
Keep a stable tracking value in text, binary, header, or JSON payload data so LoadStrike can match the workflow.
Java limits each fully reassembled inbound text or binary message to 1 MiB. Its deprecated TrackPingPong, TrackCloseCodes, and TrackMessageLatency compatibility fields have no effect and add no metrics.
This C# sample uses native Produce. Every supported SDK can use native or delegate-backed Produce and Consume; a matching delegate owns execution. Go names those fields Produce and Consume, while async-named SDKs expose ProduceAsync and ConsumeAsync.