WebSocket-Verbindungen mit Bash testen: Handshake, Ping/Pong und CI

1. Warum sich WebSocket-Tests von HTTP-Requests unterscheiden

Ein normaler HTTP-Request ist abgeschlossen, sobald die Antwort eintrifft. Eine WebSocket-Verbindung dagegen bleibt offen, sendet und empfängt Frames in beide Richtungen und lebt oft Minuten oder Stunden. Wer WebSocket-Verbindungen mit Bash testen möchte, muss deshalb nicht nur einen einzelnen Request prüfen, sondern das Verhalten über die gesamte Lebensdauer der Verbindung: Handshake, Datenaustausch, Keep-Alive und sauberen Verbindungsabbau.

Klassische Tools wie curl ohne Zusatzoptionen scheitern hier, weil sie für Request-Response-Zyklen gebaut sind, nicht für langlebige, bidirektionale Streams. Genau deshalb lohnt es sich, WebSocket-Verbindungen mit Bash gezielt zu testen: Ein Shell-Skript kann den Handshake auslösen, den Upgrade auf das WebSocket-Protokoll prüfen, Frames senden und die Antwort validieren, komplett headless und reproduzierbar in jeder Pipeline.

In der Praxis betrifft das Chat-Systeme, Live-Preisfeeds, Benachrichtigungsdienste und Magento-Erweiterungen mit Echtzeit-Updates im Adminbereich. Ein Ausfall der WebSocket-Verbindung fällt im Browser oft erst durch fehlendes Feedback auf. Ein automatisierter Test, der WebSocket-Verbindungen mit Bash prüft, erkennt das Problem, bevor der Nutzer es tut.

2. Werkzeuge: openssl, curl und websocat im Überblick

Drei Werkzeuge decken die meisten Anwendungsfälle ab, wenn man WebSocket-Verbindungen mit Bash testen will. openssl s_client stellt eine rohe TLS- oder TCP-Verbindung her und erlaubt es, den HTTP-Upgrade-Request von Hand zu senden. Das ist mühsam, zeigt aber jedes Byte des Protokolls und eignet sich hervorragend zum Debuggen von Handshake-Problemen.

Moderne curl-Versionen (ab 7.86) unterstützen WebSocket experimentell über curl --http1.1 -N mit den passenden Upgrade-Headern, sind für produktive Testskripte aber noch nicht immer verfügbar, da viele Distributionen ältere curl-Builds ausliefern. Das dritte und in der Praxis wichtigste Werkzeug ist websocat, ein einzelnes statisches Binary, das WebSocket-Verbindungen wie eine Pipe behandelt: stdin rein, stdout raus. Damit lassen sich WebSocket-Verbindungen mit Bash testen, ohne eine einzige Zeile Handshake-Code selbst zu schreiben.

Für CI-Umgebungen ist websocat ideal, weil es keine Laufzeitabhängigkeiten hat und sich als einzelne Binärdatei in ein Docker-Image kopieren lässt. Für punktuelles Debugging auf einem Produktionsserver, auf dem kein websocat installiert werden darf, bleibt openssl s_client die Rettung, weil openssl praktisch überall vorhanden ist.

#!/usr/bin/env bash
# check-tools.sh — verify which WebSocket testing tools are available
set -euo pipefail

check_tool() {
  local name="$1"
  if command -v "$name" &>/dev/null; then
    echo "[OK] $name found: $(command -v "$name")"
    return 0
  fi
  echo "[MISSING] $name not found" >&2
  return 1
}

echo "=== WebSocket toolchain check ==="
check_tool openssl || true
check_tool curl || true
check_tool websocat || echo "  Install: cargo install websocat OR download static binary"

3. Den WebSocket-Handshake manuell nachbauen

Der WebSocket-Handshake ist ein normaler HTTP-Request mit einem entscheidenden Unterschied: dem Header Upgrade: websocket zusammen mit Connection: Upgrade und einem zufälligen Base64-Wert in Sec-WebSocket-Key. Der Server antwortet mit Statuscode 101 Switching Protocols und einem berechneten Sec-WebSocket-Accept, der aus dem gesendeten Key plus einer festen GUID per SHA1 gebildet wird. Wer diesen Ablauf einmal von Hand nachbaut, versteht WebSocket-Verbindungen in Bash danach deutlich besser als über jede Dokumentation.

Mit openssl s_client -connect host:443 -quiet öffnet man die TLS-Verbindung, schreibt dann den Upgrade-Request inklusive aller Pflicht-Header hinein und liest die Antwort. Der Schlüssel für den Sec-WebSocket-Key muss laut Spezifikation aus 16 zufälligen Bytes, Base64-kodiert, bestehen. Bash erzeugt das bequem mit openssl rand -base64 16.

#!/usr/bin/env bash
# manual-handshake.sh — build a raw WebSocket upgrade request by hand
set -euo pipefail

HOST="echo.websocket.org"
PORT=443
WS_KEY=$(openssl rand -base64 16)

# Build the upgrade request as a here-doc, CRLF line endings required
request=$(printf 'GET / HTTP/1.1\r\nHost: %s\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Key: %s\r\nSec-WebSocket-Version: 13\r\n\r\n' "$HOST" "$WS_KEY")

echo "[INFO] Sending handshake with Sec-WebSocket-Key: $WS_KEY"

# Send request through a TLS connection and capture the first response lines
response=$(printf '%s' "$request" | timeout 5 openssl s_client -connect "$HOST:$PORT" -quiet 2>/dev/null | head -n 10)

if echo "$response" | grep -q "101 Switching Protocols"; then
  echo "[OK] Server upgraded the connection to WebSocket"
else
  echo "[FAIL] Handshake did not succeed:" >&2
  echo "$response" >&2
  exit 1
fi

Dieses Skript prüft nur den Handshake, nicht den Datenaustausch danach, das reicht aber schon aus, um festzustellen, ob ein Reverse Proxy oder eine Firewall den Upgrade blockiert. Wer WebSocket-Verbindungen mit Bash testen will, sollte diesen Baustein isoliert vom Rest behalten, weil Handshake-Fehler und Datenübertragungsfehler völlig unterschiedliche Ursachen haben.

4. websocat als natives Bash-Testwerkzeug einsetzen

Statt den Handshake und das Frame-Format von Hand zu bauen, übernimmt websocat beides und verhält sich danach wie ein bidirektionaler Pipe-Endpunkt. Ein einfacher Aufruf echo "ping" | websocat wss://example.com/ws öffnet die Verbindung, sendet die Nachricht als Textframe und gibt jede empfangene Antwort auf stdout aus. Das macht es trivial, WebSocket-Verbindungen mit Bash zu testen, ohne sich um Frame-Maskierung, Opcode-Bytes oder Fragmentierung zu kümmern.

Für automatisierte Tests kombiniert man websocat mit timeout, damit ein Skript nicht endlos auf eine Antwort wartet, die nie kommt. Die Option -n1 beendet websocat nach dem ersten empfangenen Frame, was für einfache Request-Response-artige WebSocket-APIs (etwa JSON-RPC über WebSocket) ideal ist. Für Streaming-Endpunkte, die kontinuierlich Daten senden, liest man stattdessen eine feste Anzahl Zeilen mit head -n N.

#!/usr/bin/env bash
# ws-test.sh — send a message and validate the WebSocket response with websocat
set -euo pipefail

WS_URL="${1:?Usage: ws-test.sh <ws-url> <message>}"
MESSAGE="${2:?Missing message payload}"
TIMEOUT_SECONDS=5

response=$(echo "$MESSAGE" | timeout "$TIMEOUT_SECONDS" websocat -n1 "$WS_URL" 2>/dev/null) || {
  echo "[FAIL] No response within ${TIMEOUT_SECONDS}s or connection error" >&2
  exit 1
}

if [[ -z "$response" ]]; then
  echo "[FAIL] Empty response from $WS_URL" >&2
  exit 1
fi

echo "[OK] Response: $response"

# Validate the response is well-formed JSON, if the API returns JSON
if command -v jq &>/dev/null; then
  echo "$response" | jq -e . >/dev/null 2>&1 && echo "[OK] Response is valid JSON"
fi

5. Ping/Pong-Frames und Verbindungsstabilität prüfen

WebSocket definiert eigene Kontrollframes für Ping und Pong, unabhängig von den eigentlichen Nutzdaten. Ein Server sendet periodisch einen Ping-Frame, der Client muss mit einem Pong-Frame antworten, sonst betrachtet der Server die Verbindung als tot und schließt sie. Wer WebSocket-Verbindungen mit Bash testen will, sollte deshalb prüfen, ob der eigene Client oder der getestete Server auf diese Kontrollframes korrekt reagiert, weil genau hier viele Implementierungen nach längerer Inaktivität stillschweigend die Verbindung verlieren.

websocat unterstützt automatisches Ping mit der Option --ping-interval, was sich hervorragend für Langzeittests eignet: Man öffnet eine Verbindung, lässt sie mehrere Minuten mit aktivem Ping-Pong offen und prüft danach, ob sie noch reagiert. Das deckt Probleme auf, die ein einzelner kurzer Test niemals findet, etwa Load Balancer, die Idle-Verbindungen nach 60 Sekunden ohne Traffic kappen.

#!/usr/bin/env bash
# ws-stability.sh — keep a WebSocket connection open and verify ping/pong survival
set -euo pipefail

WS_URL="${1:?Usage: ws-stability.sh <ws-url> <duration-seconds>}"
DURATION="${2:-120}"

echo "[INFO] Holding connection open for ${DURATION}s with automatic ping every 20s"

# --ping-interval keeps the connection alive; -E exits on first error
if timeout "$((DURATION + 5))" websocat --ping-interval 20 -E "$WS_URL" < /dev/null > /tmp/ws-session.log 2>&1; then
  echo "[OK] Connection survived ${DURATION}s of ping/pong"
else
  exit_code=$?
  echo "[FAIL] Connection dropped or errored after less than ${DURATION}s (exit $exit_code)" >&2
  tail -n 5 /tmp/ws-session.log >&2
  exit 1
fi

6. Automatisierte Testskripte für CI-Pipelines

In einer CI-Pipeline zählt vor allem ein klarer Exit-Code: 0 für erfolgreich, ungleich 0 für fehlgeschlagen. Ein Skript, das WebSocket-Verbindungen mit Bash testet, sollte deshalb Handshake, Nachrichtenaustausch und sauberen Verbindungsabbau in einer Funktion kapseln und bei jedem Fehlschlag sofort mit aussagekräftiger Meldung abbrechen. set -euo pipefail ist hier ebenso Pflicht wie in jedem anderen produktiven Bash-Skript.

Für GitLab CI oder GitHub Actions reicht ein Job, der websocat als statisches Binary aus dem Cache oder per curl herunterlädt, den Testendpunkt gegen den Feature-Branch startet und das Testskript ausführt. Retries mit begrenzter Anzahl fangen flackernde Netzwerkverbindungen in der CI-Umgebung ab, ohne echte Fehler zu verschleiern.

7. Fehlerdiagnose: Timeouts, Proxys und TLS-Probleme

Die häufigste Fehlerquelle beim Testen ist nicht der WebSocket-Server selbst, sondern ein Reverse Proxy dazwischen, der den Upgrade-Header verwirft. Nginx zum Beispiel benötigt explizite Konfiguration mit proxy_set_header Upgrade $http_upgrade; und proxy_set_header Connection "upgrade";, sonst wird aus dem WebSocket-Handshake ein normaler HTTP-Request, der mit Status 400 oder 426 scheitert. Wer WebSocket-Verbindungen mit Bash testen und dabei einen Fehlschlag direkt am Proxy erkennen will, prüft zuerst den Statuscode der Antwort, bevor er tiefer im Stack sucht.

TLS-Probleme äußern sich anders: openssl s_client -connect host:443 -showcerts zeigt die komplette Zertifikatskette und deckt sofort auf, ob ein Zwischenzertifikat fehlt oder das Zertifikat bereits abgelaufen ist. Timeout-Probleme wiederum treten meist bei Load Balancern auf, die Idle-Connections nach einer festen Zeit trennen, ohne einen Close-Frame zu senden, das Skript hängt dann in einem read ohne Antwort, weshalb ein expliziter timeout-Wrapper um jeden Testaufruf Pflicht ist.

Ein dritter, oft übersehener Fall: Manche APIs verlangen zusätzliche Header wie ein Authentifizierungstoken bereits im Upgrade-Request, nicht erst nach dem Handshake. Fehlt dieser Header, antwortet der Server oft mit einem generischen 401, was leicht mit einem grundsätzlichen Handshake-Problem verwechselt wird.

8. Logging und Monitoring von WebSocket-Sessions

Für produktive Überwachung reicht ein einmaliger Test nicht aus. Ein Monitoring-Skript, das WebSocket-Verbindungen mit Bash regelmäßig prüft, sollte Zeitstempel, Antwortzeit des Handshakes und die Dauer bis zur ersten Nutzdaten-Antwort protokollieren. Diese Werte lassen sich in eine einfache CSV-Datei schreiben oder direkt an ein Monitoring-System wie Prometheus über den Node Exporter Textfile Collector übergeben.

Wichtig ist eine klare Trennung zwischen Handshake-Fehlern, Timeout-Fehlern und Protokollfehlern in den Log-Zeilen, weil diese drei Kategorien unterschiedliche Ursachen und unterschiedliche Verantwortliche haben: Netzwerk-Team, Anwendungs-Team oder Infrastruktur-Team. Ein Cronjob, der alle fünf Minuten läuft und bei drei aufeinanderfolgenden Fehlschlägen eine Benachrichtigung auslöst, verhindert Fehlalarme durch einzelne kurze Netzwerkschwankungen, meldet aber echte Ausfälle zuverlässig.

9. Werkzeuge für WebSocket-Verbindungen im Vergleich

Die Tabelle in Abschnitt sechs zeigt bereits die zentralen Empfehlungen, doch es lohnt sich, die Werkzeuge auch nach Einsatzort zu unterscheiden. Auf einem Produktionsserver ohne zusätzliche Software ist openssl s_client oft die einzige Option, um WebSocket-Verbindungen mit Bash zu testen. In CI-Umgebungen, in denen man die Kontrolle über das Image hat, ist websocat die deutlich komfortablere Wahl, weil es Handshake und Framing vollständig übernimmt.

curl mit experimenteller WebSocket-Unterstützung eignet sich vor allem dann, wenn ein Team bereits stark auf curl für alle anderen API-Tests setzt und Konsistenz im Tooling wichtiger ist als volle Feature-Abdeckung. Für komplexere Testszenarien mit mehreren gleichzeitigen Verbindungen oder Lasttests bleibt websocat die robusteste Basis, weil es sich in einfache Bash-Schleifen mit Hintergrundprozessen einbetten lässt.

10. Zusammenfassung

WebSocket-Verbindungen mit Bash testen bedeutet, den Handshake, den Nachrichtenaustausch und die Verbindungsstabilität einzeln und automatisiert zu prüfen. openssl s_client eignet sich für die manuelle Diagnose von Handshake- und TLS-Problemen, während websocat für automatisierte Tests und CI-Integration die praktischste Wahl ist. Ping/Pong-Kontrollframes zeigen, ob eine Verbindung über längere Zeit stabil bleibt, was gerade hinter Load Balancern und Reverse Proxys entscheidend ist.

Der größte Gewinn entsteht, wenn Teams WebSocket-Tests genauso selbstverständlich in CI integrieren wie klassische HTTP-Tests. Ein Skript mit set -euo pipefail, klaren Exit-Codes und sauberer Trennung zwischen Handshake-, Timeout- und Protokollfehlern liefert Ergebnisse, auf die sich ein Team verlassen kann, ohne jedes Mal manuell im Browser nachzuschauen.

11. FAQ: WebSocket-Verbindungen mit Bash testen