WebSocket te proporciona un canal persistente y bidireccional entre cliente y servidor a través de una única conexión TCP. Una vez que la conexión está abierta, cualquiera de las partes puede enviar un mensaje en cualquier momento, lo que la convierte en la columna vertebral de los chats en vivo, los feeds de operaciones, los juegos multijugador y los paneles de control. Probarlo es un ejercicio diferente a probar una API de solicitud-respuesta, porque no hay una única respuesta que inspeccionar. Hay un flujo.
Esta guía es práctica. Cubre lo que curl puede y no puede hacer con WebSocket, cómo usar la herramienta dedicada websocat y cuándo un cliente GUI es la mejor opción. Cada comando aquí es real y está listo para copiar.
Por qué las pruebas de WebSocket no son como las pruebas REST
Una prueba REST es una transacción. Envías una solicitud, recibes una respuesta, la verificas y terminas. Una prueba WebSocket es una conversación. Abres una conexión una vez, luego intercambias muchos mensajes durante su vida útil, y los mensajes pueden llegar sin que los solicites.
Esto cambia lo que verificas. Confirmas que la conexión se actualiza correctamente desde HTTP. Confirmas que el servidor acepta tu primer mensaje y responde como se esperaba. Confirmas que los mensajes enviados por el servidor llegan sin que los solicites. Observas cómo se cierra la conexión y con qué código de cierre. Una herramienta creada para solicitudes únicas tiene dificultades con todo esto, por lo que curl, la herramienta HTTP universal, es solo una solución parcial. Para una imagen más amplia de las pruebas, la diferencia entre un escenario de prueba y un caso de prueba se alinea perfectamente con una conversación WebSocket versus una verificación de un solo mensaje.
El handshake de WebSocket
Cada conexión WebSocket comienza como una solicitud HTTP que pide ser actualizada. El cliente envía los encabezados Upgrade: websocket y Connection: Upgrade, además de una Sec-WebSocket-Key, y el servidor responde con HTTP 101 Switching Protocols. Después de eso, la conexión ya no es HTTP. Habla el protocolo de tramas de WebSocket definido en RFC 6455.
Esta es la raíz de la limitación de curl. El curl clásico habla HTTP. Puede enviar los encabezados de actualización, pero no puede enmarcar y desenmarcar mensajes WebSocket después del handshake. Intentar simular una sesión WebSocket completa con banderas de encabezado sin procesar no funciona más allá del propio handshake. Necesitas una herramienta que entienda las tramas.
Probando WebSocket con curl
Las versiones modernas de curl, 7.86 y posteriores, añadieron soporte nativo experimental para WebSocket. Es genuinamente utilizable para comprobaciones sencillas, con la advertencia de que todavía está marcado como experimental.
Primero, confirma tu versión:
curl --version
Si tienes la versión 7.86 o posterior, puedes conectarte directamente a un endpoint WebSocket. Aquí tienes una conexión a un servidor echo público, que responde con lo que le envíes:
curl --include --no-buffer \
--header "Connection: Upgrade" \
--header "Upgrade: websocket" \
--header "Sec-WebSocket-Version: 13" \
--header "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
https://echo.websocket.org
La bandera --include muestra los encabezados de la respuesta para que puedas confirmar el estado 101, y --no-buffer evita que curl retenga la salida, lo cual es importante para un flujo. Para conexiones seguras, usa una URL wss:// exactamente como usarías https://.
El soporte de WebSocket de curl destaca por una cosa: confirmar que un endpoint es accesible y que completa la actualización. Es incómodo para una sesión interactiva donde envías varios mensajes y lees respuestas, porque curl no está construido alrededor de un bucle de mensajes. Para una comprobación rápida de "está vivo este endpoint" en un script, está bien. Para pruebas interactivas reales, recurre a una herramienta dedicada. Si estás automatizando estas comprobaciones en una pipeline, nuestra guía sobre cómo automatizar pruebas de API en CI/CD cubre cómo integrar comprobaciones de línea de comandos en una compilación.
Probando WebSocket con websocat
websocat es la herramienta de línea de comandos que la mayoría de la gente realmente quiere para trabajar con WebSocket. Está diseñada específicamente para ello, entiende las tramas correctamente y se comporta como un netcat para WebSocket.
Instálalo con tu gestor de paquetes, por ejemplo, brew install websocat en macOS o mediante cargo install websocat. Luego, conectarse y chatear es un solo comando:
websocat wss://echo.websocket.org
Esto abre una sesión interactiva. Escribe una línea, presiona enter, y se envía como un mensaje. Las respuestas del servidor se imprimen a medida que llegan. Para enviar un solo mensaje y salir, redirígelo:
echo '{"action":"subscribe","channel":"prices"}' | websocat wss://stream.example.com/feed
websocat también maneja extras útiles. Puedes pasar encabezados para endpoints autenticados:
websocat --header "Authorization: Bearer your-token-here" wss://api.example.com/socket
Y puedes ejecutarlo como un servidor local para probar un cliente, o tender un puente entre un WebSocket y un puerto TCP simple. Para las pruebas de WebSocket en línea de comandos, websocat cubre casi todo lo que curl no puede. Trata las aserciones de la misma manera que lo harías en otros lugares; nuestras notas sobre escribir aserciones de API útiles también se aplican a la comprobación de las cargas útiles de los mensajes.
Probando WebSocket con una herramienta GUI
Las herramientas de línea de comandos son excelentes para scripts y comprobaciones rápidas. Son agotadoras para pruebas exploratorias, donde quieres ver la línea de tiempo de los mensajes, enviar JSON estructurado cómodamente y mantener una conexión abierta mientras la manipulas.
Apidog tiene un cliente WebSocket dedicado construido para esto. Ingresas una URL ws:// o wss://, te conectas y ves cada mensaje enviado y recibido en una vista de línea de tiempo con resaltado de sintaxis JSON. Puedes guardar conexiones, configurar encabezados y parámetros de consulta para la autenticación, y mantener la conexión activa mientras experimentas. Maneja REST, GraphQL y SOAP en la misma aplicación, por lo que las pruebas de WebSocket se realizan junto con el resto de tu trabajo de API en lugar de en una herramienta separada. Descarga Apidog para probar endpoints WebSocket con una línea de tiempo visual.
Una GUI es la elección correcta cuando estás explorando una API WebSocket desconocida, depurando por qué no llegan los mensajes o compartiendo una prueba reproducible con un compañero de equipo. La línea de comandos es la elección correcta cuando quieres que la comprobación se ejecute sin supervisión. La mayoría de los ingenieros usan ambos, eligiendo según la tarea. Si deseas una visión más amplia de las opciones de GUI, nuestro resumen de herramientas gratuitas de prueba de API en línea incluye varias que manejan WebSocket.
Una lista de verificación sencilla para pruebas WebSocket
- Confirma la actualización. La conexión debe devolver HTTP 101. Si no lo hace, el endpoint, la ruta o tus encabezados son incorrectos.
- Verifica la autenticación. Muchos servidores WebSocket esperan un token en un encabezado o parámetro de consulta. Una conexión que se abre y luego se cierra inmediatamente a menudo significa un token rechazado.
- Envía un mensaje conocido y verifica la respuesta. Utiliza una carga útil real que tu API entienda y confirma la forma de la respuesta.
- Verifica los mensajes enviados por el servidor. Suscríbete a un canal y confirma que las actualizaciones llegan sin más solicitudes de tu parte.
- Prueba el cierre. Cierra la conexión y verifica el código de cierre. Un cierre limpio es 1000; otros códigos señalan problemas específicos.
- Prueba las rutas de falla. Envía un mensaje mal formado y confirma que el servidor responde de manera sensible en lugar de desconectarse silenciosamente.
Para organizar estos elementos en un conjunto repetible, nuestra guía sobre cómo construir suites de prueba de API se aplica a los flujos de WebSocket tanto como a REST.
Depurando una conexión WebSocket que no funciona
Cuando una conexión WebSocket falla, la causa es casi siempre uno de un pequeño conjunto de problemas. Revísalos en orden.
Comienza con el esquema de la URL. Una conexión a wss:// desde una página o contexto que espera ws://, o viceversa, falla inmediatamente. Los navegadores también bloquean una conexión ws:// desde una página servida sobre HTTPS, ya que eso mezcla contenido seguro e inseguro. Confirma que el esquema coincide con el entorno.
Luego, verifica la respuesta del handshake. Si no ves HTTP 101, el servidor nunca aceptó la actualización. Un 404 significa que la ruta es incorrecta. Un 401 o 403 significa que la autenticación falló antes de la actualización. Un 400 a menudo significa un encabezado de actualización faltante o mal formado. La bandera --include de curl y el modo verboso de websocat te muestran esta respuesta, para que puedas distinguir un fallo del handshake de un problema posterior.
Si el handshake tiene éxito pero la conexión se interrumpe segundos después, busca los tiempos de espera por inactividad y los frames ping o pong. Muchos servidores esperan que el cliente responda a los frames ping para demostrar que sigue activo, y cierran las conexiones que se quedan en silencio. Un proxy o balanceador de carga delante del servidor también puede cerrar conexiones inactivas según su propia programación. Finalmente, lee el código de cierre. Los códigos están definidos en RFC 6455, y un código como 1006 apunta a un cierre anormal sin un handshake limpio, mientras que 1011 indica un error del servidor. El código de cierre generalmente te dice qué lado se rindió y por qué.
Automatizando las comprobaciones de WebSocket
Una prueba manual única confirma que un endpoint funciona hoy. No te protege de una regresión la próxima semana. Para eso, la comprobación de WebSocket debe ejecutarse sin supervisión.
Las herramientas de línea de comandos lo hacen sencillo. Un pequeño script puede abrir una conexión con websocat, enviar un mensaje conocido, capturar la respuesta y compararla con un valor esperado, luego salir con un código distinto de cero si no coincide. Ese script se integra en una pipeline de CI como cualquier otro paso de prueba. Una herramienta GUI con un ejecutor de escenarios, como Apidog, puede guardar un flujo de WebSocket, incluyendo los mensajes enviados y las aserciones sobre las respuestas, y reproducirlo en un horario o desde un disparador de pipeline.
Mantén las pruebas automatizadas de WebSocket enfocadas. Asegura que la conexión se actualice, asegura un par conocido de solicitud y respuesta, y asegura que un canal suscrito entrega al menos un mensaje enviado dentro de un tiempo de espera. Intentar asegurar cada posible mensaje de una conexión de larga duración hace que la prueba sea lenta y poco fiable. La misma moderación que mantiene un caso de prueba preciso, mantiene una comprobación WebSocket fiable: prueba una cosa clara, y pruébala bien.
Preguntas frecuentes
¿Puede curl probar conexiones WebSocket?
Parcialmente. curl 7.86 y posteriores tiene soporte nativo experimental para WebSocket que puede completar el handshake e intercambiar mensajes básicos, lo cual es suficiente para confirmar que un endpoint es accesible. Es incómodo para sesiones interactivas con muchos mensajes. Para pruebas WebSocket reales, websocat o un cliente GUI como Apidog son una mejor opción.
¿Cuál es la diferencia entre ws y wss?
ws:// es una conexión WebSocket no cifrada, y wss:// está cifrada con TLS, el equivalente WebSocket de HTTP versus HTTPS. Siempre usa wss:// para cualquier cosa más allá del desarrollo local, ya que ws:// envía mensajes en texto plano. Las herramientas tratan ambas URLs de forma idéntica, excepto por el cifrado.
¿Por qué mi conexión WebSocket se abre y luego se cierra inmediatamente?
La causa más común es la autenticación. Si el servidor espera un token en un encabezado o parámetro de consulta y no recibe uno válido, acepta la conexión TCP y luego la cierra. Verifica el código de cierre, valida tu token y confirma que lo estás enviando de la manera que el servidor espera.
¿Es websocat mejor que curl para probar WebSocket?
Para WebSocket específicamente, sí. websocat está diseñado para ello, entiende completamente el protocolo de tramas, soporta sesiones interactivas, encabezados personalizados y la redirección de mensajes de entrada y salida. curl es una herramienta HTTP general cuyo soporte para WebSocket todavía es experimental. Usa curl para una comprobación rápida de accesibilidad y websocat para pruebas reales.
¿Cómo pruebo que un servidor envía mensajes sin una solicitud?
Abre la conexión, suscríbete al canal o evento relevante si la API lo requiere, luego espera y observa. Con websocat, los mensajes enviados se imprimen a medida que llegan. Con un cliente GUI como Apidog, aparecen en la línea de tiempo de mensajes. Confirma que los mensajes llegan sin ninguna entrada adicional de tu parte, ya que la entrega no solicitada es el propósito de WebSocket.