WebSocket vous offre un canal persistant et bidirectionnel entre le client et le serveur sur une seule connexion TCP. Une fois la connexion ouverte, chaque partie peut envoyer un message à tout moment, ce qui en fait la colonne vertébrale des chats en direct, des flux de trading, des jeux multijoueurs et des tableaux de bord. Le tester est un exercice différent de celui de tester une API de type requête-réponse, car il n'y a pas de réponse unique à inspecter. Il y a un flux.
Ce guide est pratique. Il couvre ce que curl peut et ne peut pas faire avec WebSocket, comment utiliser l'outil dédié websocat, et quand un client GUI est le meilleur choix. Chaque commande ici est réelle et prête à être copiée.
Pourquoi le test WebSocket n'est pas comme le test REST
Un test REST est une transaction. Vous envoyez une requête, vous obteniez une réponse, vous l'affirmez, et vous avez terminé. Un test WebSocket est une conversation. Vous ouvrez une connexion une seule fois, puis vous échangez de nombreux messages tout au long de sa durée de vie, et les messages peuvent arriver sans y être invités.
Cela change ce que vous vérifiez. Vous confirmez que la connexion est correctement mise à niveau depuis HTTP. Vous confirmez que le serveur accepte votre premier message et répond comme prévu. Vous confirmez que les messages poussés par le serveur arrivent sans que vous les demandiez. Vous observez comment la connexion se ferme et avec quel code de fermeture. Un outil conçu pour des requêtes ponctuelles a du mal avec tout cela, c'est pourquoi curl, l'outil HTTP universel, n'est qu'un ajustement partiel. Pour une vision plus large des tests, la différence entre un scénario de test et un cas de test correspond parfaitement à une conversation WebSocket par rapport à une vérification de message unique.
Le handshake WebSocket
Chaque connexion WebSocket commence comme une requête HTTP qui demande à être mise à niveau. Le client envoie les en-têtes Upgrade: websocket et Connection: Upgrade ainsi qu'une Sec-WebSocket-Key, et le serveur répond avec HTTP 101 Switching Protocols. Après cela, la connexion n'est plus HTTP. Elle utilise le protocole de trames WebSocket défini dans la RFC 6455.
C'est la racine de la limitation de curl. Le curl classique parle HTTP. Il peut envoyer les en-têtes de mise à niveau, mais il ne peut pas encapsuler et désencapsuler les messages WebSocket après le handshake. Essayer de simuler une session WebSocket complète avec des drapeaux d'en-tête bruts ne fonctionne pas au-delà du handshake lui-même. Vous avez besoin d'un outil qui comprend les trames.
Tester WebSocket avec curl
Le curl moderne, version 7.86 et ultérieure, a ajouté un support WebSocket natif expérimental. Il est réellement utilisable pour des vérifications simples, avec la mise en garde qu'il est toujours marqué comme expérimental.
Confirmez d'abord votre version :
curl --version
Si vous utilisez la version 7.86 ou une version plus récente, vous pouvez vous connecter directement à un point de terminaison WebSocket. Voici une connexion à un serveur d'écho public, qui répond avec tout ce que vous envoyez :
curl --include --no-buffer \
--header "Connection: Upgrade" \
--header "Upgrade: websocket" \
--header "Sec-WebSocket-Version: 13" \
--header "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
https://echo.websocket.org
L'option --include affiche les en-têtes de réponse afin que vous puissiez confirmer le statut 101, et --no-buffer empêche curl de retenir la sortie, ce qui est important pour un flux. Pour les connexions sécurisées, utilisez une URL wss:// exactement comme vous le feriez pour https://.
Le support WebSocket de curl brille pour une chose : confirmer qu'un point de terminaison est accessible et que la mise à niveau est terminée. Il est peu pratique pour une session interactive où vous envoyez plusieurs messages et lisez les réponses, car curl n'est pas conçu autour d'une boucle de messages. Pour une vérification rapide "ce point de terminaison est-il actif" dans un script, c'est bien. Pour des tests interactifs réels, utilisez un outil dédié. Si vous scriptiez ces vérifications dans un pipeline, notre guide sur l'automatisation des tests d'API en CI/CD couvre l'intégration des vérifications en ligne de commande dans une build.
Tester WebSocket avec websocat
websocat est l'outil en ligne de commande que la plupart des gens souhaitent réellement pour travailler avec WebSocket. Il est conçu spécifiquement pour cela, comprend correctement les trames et se comporte comme un netcat pour WebSocket.
Installez-le avec votre gestionnaire de paquets, par exemple brew install websocat sur macOS ou via cargo install websocat. Ensuite, la connexion et le chat se font avec une seule commande :
websocat wss://echo.websocket.org
Cela ouvre une session interactive. Tapez une ligne, appuyez sur Entrée, et elle est envoyée comme message. Les réponses du serveur s'affichent au fur et à mesure qu'elles arrivent. Pour envoyer un seul message et quitter, utilisez un pipe :
echo '{"action":"subscribe","channel":"prices"}' | websocat wss://stream.example.com/feed
websocat gère également des extras utiles. Vous pouvez transmettre des en-têtes pour les points de terminaison authentifiés :
websocat --header "Authorization: Bearer your-token-here" wss://api.example.com/socket
Et vous pouvez l'exécuter comme un serveur local pour tester un client, ou relier un WebSocket à un port TCP simple. Pour les tests WebSocket en ligne de commande, websocat couvre presque tout ce que curl ne peut pas faire. Traitez les assertions de la même manière que vous le feriez ailleurs ; nos notes sur la rédaction d'assertions API utiles s'appliquent également à la vérification des charges utiles des messages.
Tester WebSocket avec un outil GUI
Les outils en ligne de commande sont excellents pour les scripts et les vérifications rapides. Ils sont fastidieux pour les tests exploratoires, où vous souhaitez voir la chronologie des messages, envoyer des JSON structurés confortablement et maintenir une connexion ouverte pendant que vous l'examinez.
Apidog dispose d'un client WebSocket dédié conçu à cet effet. Vous entrez une URL ws:// ou wss://, vous vous connectez, et vous voyez chaque message envoyé et reçu dans une vue chronologique avec la coloration syntaxique JSON. Vous pouvez enregistrer les connexions, définir des en-têtes et des paramètres de requête pour l'authentification, et maintenir la connexion active pendant que vous expérimentez. Il gère REST, GraphQL et SOAP dans la même application, de sorte que les tests WebSocket s'intègrent au reste de votre travail sur les API plutôt que dans un outil séparé. Téléchargez Apidog pour tester les points de terminaison WebSocket avec une chronologie visuelle.
Une interface graphique est le bon choix lorsque vous explorez une API WebSocket inconnue, que vous déboguez pourquoi les messages n'arrivent pas, ou que vous partagez un test reproductible avec un coéquipier. La ligne de commande est le bon choix lorsque vous voulez que la vérification s'exécute sans surveillance. La plupart des ingénieurs utilisent les deux, en choisissant en fonction de la tâche. Si vous souhaitez une vue plus large des options d'interface graphique, notre récapitulatif des outils de test d'API en ligne gratuits en inclut plusieurs qui gèrent WebSocket.
Une simple liste de contrôle pour les tests WebSocket
- Confirmez la mise à niveau. La connexion doit renvoyer HTTP 101. Si ce n'est pas le cas, le point de terminaison, le chemin ou vos en-têtes sont incorrects.
- Vérifiez l'authentification. De nombreux serveurs WebSocket s'attendent à un jeton dans un en-tête ou un paramètre de requête. Une connexion qui s'ouvre puis se ferme immédiatement signifie souvent un jeton rejeté.
- Envoyez un message connu et vérifiez la réponse. Utilisez une charge utile réelle que votre API comprend et confirmez la forme de la réponse.
- Vérifiez les messages poussés par le serveur. Abonnez-vous à un canal et confirmez que les mises à jour arrivent sans autres requêtes de votre part.
- Testez la fermeture. Fermez la connexion et vérifiez le code de fermeture. Une fermeture propre est 1000 ; d'autres codes signalent des problèmes spécifiques.
- Testez les chemins d'échec. Envoyez un message mal formé et confirmez que le serveur répond de manière sensée plutôt que de se déconnecter silencieusement.
Pour organiser ceux-ci en un ensemble reproductible, notre guide sur la création de suites de tests API s'applique aux flux WebSocket autant qu'à REST.
Déboguer une connexion WebSocket qui ne fonctionne pas
Lorsqu'une connexion WebSocket échoue, la cause est presque toujours l'un d'un petit ensemble de problèmes. Parcourez-les dans l'ordre.
Commencez par le schéma d'URL. Une connexion à wss:// depuis une page ou un contexte qui attend ws://, ou l'inverse, échoue immédiatement. Les navigateurs bloquent également une connexion ws:// depuis une page servie via HTTPS, car cela mélange du contenu sécurisé et non sécurisé. Confirmez que le schéma correspond à l'environnement.
Ensuite, vérifiez la réponse du handshake. Si vous ne voyez pas HTTP 101, le serveur n'a jamais accepté de procéder à la mise à niveau. Un 404 signifie que le chemin est incorrect. Un 401 ou 403 signifie que l'authentification a échoué avant la mise à niveau. Un 400 signifie souvent un en-tête de mise à niveau manquant ou mal formé. L'option --include de curl et le mode verbeux de websocat vous montrent tous deux cette réponse, ce qui vous permet de distinguer un échec de handshake d'un problème ultérieur.
Si le handshake réussit mais que la connexion est interrompue quelques secondes plus tard, examinez les délais d'inactivité et les trames ping ou pong. De nombreux serveurs s'attendent à ce que le client réponde aux trames ping pour prouver qu'il est toujours actif, et ils ferment les connexions qui deviennent silencieuses. Un proxy ou un équilibreur de charge devant le serveur peut également interrompre les connexions inactives selon son propre calendrier. Enfin, lisez le code de fermeture. Les codes sont définis dans la RFC 6455, et un code comme 1006 indique une fermeture anormale sans handshake propre, tandis que 1011 signale une erreur de serveur. Le code de fermeture vous indique généralement quelle partie a abandonné et pourquoi.
Automatiser les vérifications WebSocket
Un test manuel ponctuel confirme qu'un point de terminaison fonctionne aujourd'hui. Il ne vous protège pas d'une régression la semaine prochaine. Pour cela, la vérification WebSocket doit s'exécuter sans surveillance.
Les outils en ligne de commande simplifient cela. Un petit script peut ouvrir une connexion avec websocat, envoyer un message connu, capturer la réponse et la comparer à une valeur attendue, puis sortir avec un code non nul si elle ne correspond pas. Ce script s'intègre dans un pipeline CI comme n'importe quelle autre étape de test. Un outil GUI avec un exécuteur de scénarios, tel qu'Apidog, peut enregistrer un flux WebSocket, y compris les messages envoyés et les assertions sur les réponses, et le rejouer selon un calendrier ou à partir d'un déclencheur de pipeline.
Gardez les tests WebSocket automatisés ciblés. Affirmez que la connexion est mise à niveau, affirmez une paire requête-réponse connue, et affirmez qu'un canal souscrit délivre au moins un message poussé dans un délai imparti. Essayer d'affirmer chaque message possible d'une connexion de longue durée rend un test lent et instable. La même retenue qui maintient un cas de test précis maintient une vérification WebSocket fiable : testez une chose claire, et testez-la bien.
Questions fréquemment posées
Curl peut-il tester les connexions WebSocket ?
Partiellement. curl 7.86 et versions ultérieures dispose d'un support WebSocket natif expérimental capable de finaliser le handshake et d'échanger des messages de base, ce qui est suffisant pour confirmer qu'un point de terminaison est accessible. C'est peu pratique pour les sessions interactives avec de nombreux messages. Pour de véritables tests WebSocket, websocat ou un client GUI comme Apidog est plus approprié.
Quelle est la différence entre ws et wss ?
ws:// est une connexion WebSocket non chiffrée, et wss:// est chiffrée avec TLS, l'équivalent WebSocket de HTTP versus HTTPS. Utilisez toujours wss:// pour tout ce qui dépasse le développement local, car ws:// envoie les messages en texte brut. Les outils traitent les deux URL de manière identique, à l'exception du chiffrement.
Pourquoi ma connexion WebSocket s'ouvre-t-elle puis se ferme-t-elle immédiatement ?
La cause la plus fréquente est l'authentification. Si le serveur s'attend à un jeton dans un en-tête ou un paramètre de requête et n'en reçoit pas un valide, il accepte la connexion TCP puis la ferme. Vérifiez le code de fermeture, vérifiez votre jeton et confirmez que vous l'envoyez de la manière attendue par le serveur.
Websocat est-il meilleur que curl pour les tests WebSocket ?
Pour WebSocket spécifiquement, oui. websocat est conçu à cet effet, comprend entièrement le protocole de trames, prend en charge les sessions interactives, les en-têtes personnalisés et le routage des messages entrants et sortants. curl est un outil HTTP général dont le support WebSocket est encore expérimental. Utilisez curl pour une vérification rapide de l'accessibilité et websocat pour les tests réels.
Comment tester qu'un serveur envoie des messages sans requête ?
Ouvrez la connexion, abonnez-vous au canal ou à l'événement pertinent si l'API l'exige, puis attendez et observez. Avec websocat, les messages poussés s'affichent au fur et à mesure qu'ils arrivent. Avec un client GUI comme Apidog, ils apparaissent dans la chronologie des messages. Confirmez que les messages arrivent sans aucune autre intervention de votre part, car la livraison non sollicitée est le but de WebSocket.