WebSocket bietet Ihnen einen persistenten, bidirektionalen Kanal zwischen Client und Server über eine einzige TCP-Verbindung. Sobald die Verbindung offen ist, kann jede Seite jederzeit eine Nachricht senden, was es zum Rückgrat von Live-Chats, Handels-Feeds, Mehrspieler-Spielen und Dashboards macht. Das Testen unterscheidet sich vom Testen einer Request-Response-API, da es keine einzelne Antwort gibt, die inspiziert werden könnte. Es gibt einen Stream.
Dieser Leitfaden ist praxisorientiert. Er behandelt, was curl mit WebSocket tun kann und was nicht, wie das dedizierte Tool websocat verwendet wird und wann ein GUI-Client die bessere Wahl ist. Jeder Befehl hier ist real und kopierfertig.
Warum das Testen von WebSocket nicht wie das Testen von REST ist
Ein REST-Test ist eine Transaktion. Sie senden eine Anfrage, erhalten eine Antwort, bestätigen diese, und sind fertig. Ein WebSocket-Test ist eine Konversation. Sie öffnen einmal eine Verbindung, tauschen dann im Laufe ihrer Lebensdauer viele Nachrichten aus, und Nachrichten können unaufgefordert eintreffen.
Das ändert, was Sie überprüfen. Sie bestätigen, dass die Verbindung korrekt von HTTP aktualisiert wird. Sie bestätigen, dass der Server Ihre erste Nachricht akzeptiert und wie erwartet antwortet. Sie bestätigen, dass vom Server gepushte Nachrichten ankommen, ohne dass Sie danach fragen. Sie beobachten, wie die Verbindung geschlossen wird und mit welchem Schließcode. Ein Tool, das für einmalige Anfragen entwickelt wurde, hat mit all dem Schwierigkeiten, weshalb curl, das universelle HTTP-Tool, nur teilweise passt. Für das umfassendere Testbild passt die Unterscheidung zwischen einem Testszenario und einem Testfall gut zu einer WebSocket-Konversation im Vergleich zu einer einzelnen Nachrichtenprüfung.
Der WebSocket-Handshake
Jede WebSocket-Verbindung beginnt als HTTP-Anfrage, die eine Aktualisierung verlangt. Der Client sendet die Header Upgrade: websocket und Connection: Upgrade sowie einen Sec-WebSocket-Key, und der Server antwortet mit HTTP 101 Switching Protocols. Danach ist die Verbindung kein HTTP mehr. Sie spricht das in RFC 6455 definierte WebSocket-Frame-Protokoll.
Hier liegt die Einschränkung von curl. Klassisches curl spricht HTTP. Es kann die Upgrade-Header senden, aber es kann nach dem Handshake keine WebSocket-Nachrichten mehr framen und unframe. Der Versuch, eine vollständige WebSocket-Sitzung mit rohen Header-Flags zu fälschen, funktioniert über den Handshake hinaus nicht. Sie benötigen ein Tool, das Frames versteht.
WebSocket mit curl testen
Modernes curl, Version 7.86 und höher, bietet experimentelle native WebSocket-Unterstützung. Es ist für einfache Prüfungen durchaus nutzbar, mit dem Hinweis, dass es immer noch als experimentell gekennzeichnet ist.
Bestätigen Sie zuerst Ihre Version:
curl --version
Wenn Sie Version 7.86 oder neuer verwenden, können Sie sich direkt mit einem WebSocket-Endpunkt verbinden. Hier ist eine Verbindung zu einem öffentlichen Echo-Server, der mit allem antwortet, was Sie senden:
curl --include --no-buffer \
--header "Connection: Upgrade" \
--header "Upgrade: websocket" \
--header "Sec-WebSocket-Version: 13" \
--header "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
https://echo.websocket.org
Das Flag --include zeigt die Antwort-Header an, damit Sie den Status 101 bestätigen können, und --no-buffer verhindert, dass curl die Ausgabe zurückhält, was für einen Stream wichtig ist. Für sichere Verbindungen verwenden Sie eine wss://-URL genau wie https://.
Die WebSocket-Unterstützung von curl glänzt bei einer Sache: der Bestätigung, dass ein Endpunkt erreichbar ist und das Upgrade abschließt. Für eine interaktive Sitzung, in der Sie mehrere Nachrichten senden und Antworten lesen, ist sie umständlich, da curl nicht auf eine Nachrichtenschleife ausgelegt ist. Für eine schnelle "ist dieser Endpunkt aktiv"-Prüfung in einem Skript ist es in Ordnung. Für echte interaktive Tests greifen Sie zu einem dedizierten Tool. Wenn Sie diese Prüfungen in eine Pipeline skripten, behandelt unser Leitfaden zum Automatisieren von API-Tests in CI/CD die Einbindung von Befehlszeilenprüfungen in einen Build.
WebSocket mit websocat testen
websocat ist das Befehlszeilentool, das die meisten Leute tatsächlich für WebSocket-Arbeiten wünschen. Es ist speziell dafür entwickelt, versteht Frames korrekt und verhält sich wie ein Netcat für WebSocket.
Installieren Sie es mit Ihrem Paketmanager, zum Beispiel brew install websocat unter macOS oder über cargo install websocat. Dann ist die Verbindung und das Chatten ein einziger Befehl:
websocat wss://echo.websocket.org
Das öffnet eine interaktive Sitzung. Geben Sie eine Zeile ein, drücken Sie Enter, und sie wird als Nachricht gesendet. Die Antworten des Servers werden beim Eintreffen ausgegeben. Um eine einzelne Nachricht zu senden und dann zu beenden, leiten Sie sie ein:
echo '{"action":"subscribe","channel":"prices"}' | websocat wss://stream.example.com/feed
websocat beherrscht auch nützliche Extras. Sie können Header für authentifizierte Endpunkte übergeben:
websocat --header "Authorization: Bearer your-token-here" wss://api.example.com/socket
Und Sie können es als lokalen Server ausführen, um einen Client zu testen, oder ein WebSocket mit einem einfachen TCP-Port verbinden. Für Befehlszeilen-WebSocket-Tests deckt websocat fast alles ab, was curl nicht kann. Behandeln Sie Zusicherungen genauso wie anderswo; unsere Hinweise zum Schreiben nützlicher API-Zusicherungen gelten auch für die Überprüfung von Nachrichten-Payloads.
WebSocket mit einem GUI-Tool testen
Befehlszeilentools sind großartig für Skripte und schnelle Überprüfungen. Sie sind anstrengend für exploratives Testen, wo Sie den Nachrichtenverlauf sehen, strukturierte JSON bequem senden und eine Verbindung offen halten möchten, während Sie damit experimentieren.
Apidog bietet einen dedizierten WebSocket-Client dafür. Sie geben eine ws://- oder wss://-URL ein, verbinden sich und sehen jede gesendete und empfangene Nachricht in einer Zeitleistenansicht mit JSON-Syntaxhervorhebung. Sie können Verbindungen speichern, Header und Abfrageparameter für die Authentifizierung einstellen und die Verbindung während des Experimentierens aktiv halten. Es verarbeitet REST, GraphQL und SOAP in derselben Anwendung, sodass WebSocket-Tests neben dem Rest Ihrer API-Arbeit und nicht in einem separaten Tool stattfinden. Laden Sie Apidog herunter, um WebSocket-Endpunkte mit einer visuellen Zeitleiste zu testen.
Eine GUI ist die richtige Wahl, wenn Sie eine unbekannte WebSocket-API erkunden, debuggen, warum Nachrichten nicht ankommen, oder einen reproduzierbaren Test mit einem Teamkollegen teilen. Die Befehlszeile ist die richtige Wahl, wenn Sie möchten, dass die Überprüfung unbeaufsichtigt ausgeführt wird. Die meisten Ingenieure verwenden beides und wählen je nach Aufgabe. Wenn Sie einen breiteren Überblick über GUI-Optionen wünschen, enthält unsere Zusammenstellung der kostenlosen Online-API-Testtools mehrere, die WebSocket unterstützen.
Eine einfache WebSocket-Test-Checkliste
- Upgrade bestätigen. Die Verbindung sollte HTTP 101 zurückgeben. Wenn nicht, sind der Endpunkt, der Pfad oder Ihre Header falsch.
- Authentifizierung prüfen. Viele WebSocket-Server erwarten ein Token in einem Header oder Abfrageparameter. Eine Verbindung, die sich öffnet und dann sofort schließt, bedeutet oft ein abgelehntes Token.
- Eine bekannte Nachricht senden und die Antwort überprüfen. Verwenden Sie eine echte Nutzlast, die Ihre API versteht, und bestätigen Sie die Form der Antwort.
- Server-gepushte Nachrichten verifizieren. Abonnieren Sie einen Kanal und bestätigen Sie, dass Updates ohne weitere Anfragen von Ihnen ankommen.
- Den Abschluss testen. Schließen Sie die Verbindung und überprüfen Sie den Schließcode. Ein sauberer Abschluss ist 1000; andere Codes signalisieren spezifische Probleme.
- Fehlerpfade testen. Senden Sie eine fehlerhafte Nachricht und bestätigen Sie, dass der Server vernünftig reagiert, anstatt stillschweigend abzubrechen.
Für die Organisation dieser Punkte in einem wiederholbaren Satz gilt unser Leitfaden zum Erstellen von API-Test-Suites für WebSocket-Flows genauso wie für REST.
Debugging einer WebSocket-Verbindung, die nicht funktioniert
Wenn eine WebSocket-Verbindung fehlschlägt, ist die Ursache fast immer eines von wenigen Problemen. Gehen Sie diese der Reihe nach durch.
Beginnen Sie mit dem URL-Schema. Eine Verbindung zu wss:// von einer Seite oder einem Kontext, der ws:// erwartet, oder umgekehrt, schlägt sofort fehl. Browser blockieren auch eine ws://-Verbindung von einer über HTTPS bereitgestellten Seite, da dies sichere und unsichere Inhalte mischt. Bestätigen Sie, dass das Schema zur Umgebung passt.
Überprüfen Sie als Nächstes die Handshake-Antwort. Wenn Sie kein HTTP 101 sehen, hat der Server dem Upgrade nie zugestimmt. Ein 404 bedeutet, dass der Pfad falsch ist. Ein 401 oder 403 bedeutet, dass die Authentifizierung vor dem Upgrade fehlgeschlagen ist. Ein 400 bedeutet oft einen fehlenden oder fehlerhaften Upgrade-Header. Das --include-Flag von curl und der verbose-Modus von websocat zeigen Ihnen diese Antwort, sodass Sie einen Handshake-Fehler von einem späteren Problem unterscheiden können.
Wenn der Handshake erfolgreich ist, die Verbindung aber Sekunden später abbricht, suchen Sie nach Idle-Timeouts und Ping- oder Pong-Frames. Viele Server erwarten, dass der Client Ping-Frames beantwortet, um zu beweisen, dass er noch aktiv ist, und sie schließen Verbindungen, die still werden. Ein Proxy oder Load Balancer vor dem Server kann auch inaktive Verbindungen nach eigenem Zeitplan beenden. Lesen Sie schließlich den Schließcode. Die Codes sind in RFC 6455 definiert, und ein Code wie 1006 weist auf einen abnormalen Abschluss ohne sauberen Handshake hin, während 1011 einen Serverfehler signalisiert. Der Schließcode verrät Ihnen normalerweise, welche Seite aufgegeben hat und warum.
Automatisierung von WebSocket-Checks
Ein einmaliger manueller Test bestätigt, dass ein Endpunkt heute funktioniert. Er schützt Sie nicht vor einer Regression nächste Woche. Dafür muss der WebSocket-Check unbeaufsichtigt laufen.
Die Befehlszeilentools machen dies einfach. Ein kleines Skript kann mit websocat eine Verbindung öffnen, eine bekannte Nachricht senden, die Antwort erfassen und mit einem erwarteten Wert vergleichen, und dann ungleich Null beenden, wenn sie nicht übereinstimmt. Dieses Skript kann wie jeder andere Testschritt in eine CI-Pipeline integriert werden. Ein GUI-Tool mit einem Szenarien-Runner, wie Apidog, kann einen WebSocket-Flow speichern, einschließlich der gesendeten Nachrichten und der Zusicherungen auf die Antworten, und ihn nach einem Zeitplan oder über einen Pipeline-Trigger wiedergeben.
Halten Sie automatisierte WebSocket-Tests fokussiert. Bestätigen Sie, dass die Verbindung aktualisiert wird, bestätigen Sie ein bekanntes Anforderungs- und Antwortpaar und bestätigen Sie, dass ein abonnierter Kanal mindestens eine gepushte Nachricht innerhalb eines Timeouts liefert. Der Versuch, jede mögliche Nachricht einer langlebigen Verbindung zu bestätigen, macht einen Test langsam und fehleranfällig. Dieselbe Zurückhaltung, die einen Testfall präzise hält, sorgt auch dafür, dass ein WebSocket-Check zuverlässig ist: Testen Sie eine klare Sache, und testen Sie sie gut.
Häufig gestellte Fragen
Kann curl WebSocket-Verbindungen testen?
Teilweise. curl 7.86 und höher verfügt über experimentelle native WebSocket-Unterstützung, die den Handshake abschließen und grundlegende Nachrichten austauschen kann, was ausreicht, um die Erreichbarkeit eines Endpunkts zu bestätigen. Für interaktive Sitzungen mit vielen Nachrichten ist es umständlich. Für echte WebSocket-Tests ist websocat oder ein GUI-Client wie Apidog besser geeignet.
Was ist der Unterschied zwischen ws und wss?
ws:// ist eine unverschlüsselte WebSocket-Verbindung, und wss:// ist mit TLS verschlüsselt, das WebSocket-Äquivalent von HTTP versus HTTPS. Verwenden Sie immer wss:// für alles, was über die lokale Entwicklung hinausgeht, da ws:// Nachrichten im Klartext sendet. Tools behandeln die beiden URLs abgesehen von der Verschlüsselung identisch.
Warum öffnet sich meine WebSocket-Verbindung und schließt sich dann sofort wieder?
Die häufigste Ursache ist die Authentifizierung. Wenn der Server ein Token in einem Header oder Abfrageparameter erwartet und kein gültiges erhält, akzeptiert er die TCP-Verbindung und schließt sie dann. Überprüfen Sie den Schließcode, verifizieren Sie Ihr Token und bestätigen Sie, dass Sie es so senden, wie der Server es erwartet.
Ist websocat besser als curl für WebSocket-Tests?
Speziell für WebSocket, ja. websocat ist speziell dafür entwickelt, versteht das Frame-Protokoll vollständig, unterstützt interaktive Sitzungen, benutzerdefinierte Header und das Ein- und Ausleiten von Nachrichten über Pipes. curl ist ein allgemeines HTTP-Tool, dessen WebSocket-Unterstützung noch experimentell ist. Verwenden Sie curl für eine schnelle Erreichbarkeitsprüfung und websocat für tatsächliche Tests.
Wie teste ich, ob ein Server Nachrichten ohne Anfrage pusht?
Öffnen Sie die Verbindung, abonnieren Sie den relevanten Kanal oder das Ereignis, falls die API dies erfordert, und warten und beobachten Sie dann. Mit websocat werden die gepushten Nachrichten beim Eintreffen ausgegeben. Mit einem GUI-Client wie Apidog erscheinen sie in der Nachrichten-Zeitleiste. Bestätigen Sie, dass die Nachrichten ohne weitere Eingaben von Ihnen ankommen, da die unaufgeforderte Zustellung der Sinn von WebSocket ist.