WebSocket Proxy Compatibility Test: Handshake, Heartbeat and Recovery

A proxy can load ordinary HTTPS pages and still fail a browser workflow that depends on WebSockets. The opening upgrade may be rejected, authentication may work only on the first connection, idle tunnels may close silently, or a reconnect may switch region and application identity.

This guide shows how to test an authorized wss endpoint without confusing page-load success with WebSocket compatibility. Use a test service you control or have explicit permission to access. Never direct unsolicited connection tests at third-party real-time systems.

Know the layers being tested

RFC 6455 defines an HTTP opening handshake followed by bidirectional message frames. In a secure WebSocket connection, TLS is established before the WebSocket upgrade. A proxy path can therefore fail at several different layers:

1. DNS selection and route establishment;
2. proxy connection and proxy authentication;
3. TLS tunnel and certificate verification;
4. HTTP Upgrade request and 101 Switching Protocols response;
5. subprotocol or extension negotiation;
6. bidirectional text and binary frames;
7. ping, application heartbeat and idle survival;
8. close handshake and reconnection.

Record the failing layer instead of reporting only “WebSocket failed.” That distinction decides whether to change the proxy route, application configuration, certificate trust or server policy.

Build a safe echo fixture

Use a controlled endpoint with these behaviors:

• returns a unique connection alias after upgrade;
• echoes a client sequence number and payload hash;
• sends server-originated messages on a known schedule;
• supports a documented subprotocol;
• can pause output for an idle test;
• closes with a chosen close code in a fault test;
• records sanitized timestamps and connection aliases.

Do not echo credentials, cookies, full headers or arbitrary private payloads. Use synthetic text and random binary buffers that contain no customer data.

Fix the test matrix

Test one variable at a time:

Keep browser, endpoint and payload constant while comparing routes. Then keep the route constant while changing browser versions.

Capture the opening handshake

For each attempt, measure:

dns_ms
proxy_connect_ms
proxy_auth_rounds
tls_ms
upgrade_ms
upgrade_status
selected_subprotocol
selected_extensions

A valid success requires the expected endpoint, verified certificate, 101 upgrade and correct subprotocol when one is required. A normal 200 page is not a WebSocket success. A proxy-branded HTML response with 200, 403 or 407 must be classified as a gateway or authentication response, not application data.

RFC 6455 requires a client to fail the WebSocket connection if the connection cannot be opened or TLS verification fails. Do not turn off certificate verification to force a pass.

Test proxy authentication separately

Distinguish proxy authentication from origin authentication. Run these cases:

1. valid proxy credentials and valid application session;
2. invalid proxy credentials;
3. expired application session with valid proxy credentials;
4. connection reuse after successful proxy authentication;
5. reconnect after the proxy credential is rotated.

Expected failure codes and prompts should be deterministic. Credentials must never appear in WebSocket URLs, console logs, screenshots or close reasons. Use the proxy credential rotation guide to validate replacement without reusing the exposed value.

Verify bidirectional frames

After the upgrade, send numbered synthetic messages at a controlled rate. Validate both directions:

• every client sequence is acknowledged once;
• every server sequence arrives once and in the expected application order;
• payload hashes match;
• text remains valid UTF-8;
• binary payload length and hash match;
• no frame arrives on a closed or replaced connection alias.

TCP preserves byte order, but the application may process or retry messages asynchronously. Do not assume that a clean connection guarantees exactly-once business behavior.

Playwright exposes WebSocket open, frame-sent, frame-received and close events. Its WebSocket routing features can also mock or connect to a server for controlled tests. Keep mock tests separate from real proxy-path tests so a locally fulfilled socket is not counted as evidence that the route works.

Measure heartbeat and idle survival

Transport pings are not exposed consistently by every browser API, so many applications use their own heartbeat messages. Record:

heartbeat_interval_ms
last_client_message_utc
last_server_message_utc
idle_duration_ms
disconnect_detected_ms
close_code
close_reason_class

Test idle durations below, close to and above the suspected proxy timeout. Repeat at least five times. A tunnel that closes at a stable threshold suggests an idle policy; random closures correlated with load may indicate route capacity or endpoint behavior.

The proxy idle timeout and keepalive test provides a broader methodology. Do not reduce heartbeat intervals until the test proves they are necessary; aggressive heartbeats increase traffic and connection load.

Test bounded reconnection

Create three controlled failures: server close, brief client network loss and proxy refusal. For each, verify:

• the application detects loss within its deadline;
• reconnect uses exponential backoff with jitter;
• a maximum attempt and elapsed-time budget exists;
• queued messages have an explicit replay policy;
• old and new connection aliases cannot both commit the same event;
• route or region changes are visible;
• authentication is refreshed safely when required.

The proxy retry storm prevention guide helps prevent thousands of sockets from reconnecting simultaneously.

Confirm session and regional consistency

Some applications bind a WebSocket session to a login, cookie, region or backend shard. If the proxy rotates during reconnect, the application may accept the TCP/TLS connection but reject the logical session.

Record the intended proxy session alias, observed exit region and application connection alias. Test both sticky and intentionally rotated routes. The residential proxy session stickiness test separates a stable authenticated session from an assumption that the IP never changes.

Test IPv4 and IPv6 deliberately

When both families are available, record the family used for the proxy hop and the destination path visible to the controlled endpoint. Test forced IPv4, forced IPv6 and normal dual-stack selection where supported. A WebSocket that works on only one family may be hidden by automatic fallback in a simple browser test.

Do not treat IPv6 textual formatting as a credential or log full sensitive URLs. Use route aliases and sanitized address-family fields.

Classify failures

Use a small taxonomy:

• PROXY_AUTH: 407, prompt loop or credential refusal;
• PROXY_CONNECT: tunnel refusal or timeout;
• TLS_VERIFY: certificate or hostname validation failure;
• UPGRADE_REJECTED: expected 101 not returned;
• SUBPROTOCOL: required protocol not selected;
• FRAME_INTEGRITY: missing, duplicate or altered message;
• IDLE_CLOSE: repeatable idle threshold;
• RECONNECT_BUDGET: recovery exceeded limits;
• SESSION_BINDING: logical session rejected after route change;
• ENDPOINT: controlled server failure.

Quarantine only routes with repeated route-specific evidence. The proxy pool quarantine and recovery guide defines a reversible process.

Acceptance gates

A route is ready for the tested workload when:

• at least 99% of controlled upgrades succeed or meet the workload's stricter objective;
• no certificate-verification bypass is used;
• expected subprotocol negotiation passes;
• frame integrity has zero unexplained loss or duplication;
• p95 upgrade time and message round-trip stay within budget;
• idle behavior is known and heartbeat policy is justified;
• reconnection remains within attempt, time and byte budgets;
• sticky and rotating behaviors match the selected product;
• failure classification is stable across repeated samples.

Set thresholds from business requirements, not from the best observed route.

Checklist

• [ ] Endpoint ownership or testing permission is documented.
• [ ] The test uses wss and keeps certificate verification enabled.
• [ ] Proxy and origin authentication are tested separately.
• [ ] A 101 response and required subprotocol are verified.
• [ ] Text, binary and server-originated frames are checked.
• [ ] Payloads are synthetic and logs are sanitized.
• [ ] Idle thresholds and heartbeat costs are measured.
• [ ] Server close, network loss and proxy refusal are tested.
• [ ] Reconnection uses jitter and bounded budgets.
• [ ] Sticky and rotated sessions are both understood.
• [ ] IPv4 and IPv6 paths are tested where offered.
• [ ] Route quarantine requires repeated route-specific evidence.

FAQ

Does successful HTTPS browsing prove WebSocket support?

No. The proxy must also preserve the upgrade and long-lived bidirectional connection behavior required by the application.

Should I test with ws or wss?

Use wss for production-like testing because it includes TLS verification. Plain ws can be a limited lab control but should not replace the secure-path test.

Is a dropped idle socket always a proxy problem?

No. The server, load balancer, browser, operating system or network can close it. Repeat with controlled routes and correlate the threshold.

Can I log every frame for debugging?

Only synthetic test frames. Production frames may contain personal or confidential data. Prefer sequence numbers, sizes, hashes and timing.

Compliance note

Run WebSocket tests only against systems and proxy resources you are authorized to use. Respect rate limits and terms, minimize payload and log data, keep TLS verification enabled, and never use the method to bypass access controls or inspect third-party private communications.