DEV Community

Cover image for Cómo Probar Conexiones WebSocket con Curl y Otras Herramientas
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo Probar Conexiones WebSocket con Curl y Otras Herramientas

WebSocket te da un canal persistente y bidireccional entre cliente y servidor sobre una única conexión TCP. A diferencia de REST, no pruebas una respuesta aislada: pruebas un flujo de mensajes, eventos enviados por el servidor, autenticación, timeouts y cierre de conexión.

Prueba Apidog hoy

Esta guía muestra cómo probar WebSocket de forma práctica: qué puedes hacer con curl, cuándo usar websocat y cuándo conviene usar una GUI como Apidog. Todos los comandos están listos para copiar.

Por qué las pruebas de WebSocket no son como las pruebas REST

Una prueba REST suele ser una transacción:

  1. Envías una solicitud.
  2. Recibes una respuesta.
  3. Validás el estado, headers y body.
  4. Terminas.

Una prueba WebSocket es una conversación:

  1. Abres una conexión.
  2. Envías uno o varios mensajes.
  3. Recibes respuestas.
  4. Esperas mensajes enviados por el servidor.
  5. Mantienes o cierras la conexión.
  6. Validás el código de cierre.

Eso cambia lo que debes verificar:

  • Que el handshake HTTP se actualiza correctamente a WebSocket.
  • Que el servidor acepta la autenticación.
  • Que el primer mensaje válido recibe la respuesta esperada.
  • Que los mensajes enviados por el servidor llegan sin nuevas solicitudes.
  • Que los errores se reportan de forma controlada.
  • Que el cierre usa un código esperado.

Una herramienta pensada para solicitudes únicas tiene limitaciones aquí. Por eso curl sirve para comprobaciones rápidas, pero no reemplaza a una herramienta WebSocket real.

Si quieres estructurar estas pruebas, la diferencia entre un escenario de prueba y un caso de prueba encaja bien con WebSocket: una conversación completa es un escenario; un mensaje específico con respuesta esperada es un caso.

El handshake de WebSocket

Toda conexión WebSocket empieza como una solicitud HTTP que pide actualizar el protocolo.

El cliente envía headers como:

Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: ...
Sec-WebSocket-Version: 13
Enter fullscreen mode Exit fullscreen mode

Si el servidor acepta, responde:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Enter fullscreen mode Exit fullscreen mode

Después de ese 101, la conexión deja de ser HTTP y empieza a usar tramas WebSocket, definidas en RFC 6455.

Esta es la principal limitación de curl: puede iniciar el handshake, pero no siempre es cómodo para enviar, recibir y procesar tramas WebSocket durante una sesión interactiva.

Probando WebSocket con curl

Las versiones modernas de curl, desde la 7.86, incluyen soporte experimental para WebSocket.

Primero, verifica tu versión:

curl --version
Enter fullscreen mode Exit fullscreen mode

Si tienes curl 7.86 o posterior, puedes probar el handshake contra un endpoint WebSocket.

Ejemplo con un servidor echo público:

curl --include --no-buffer \
  --header "Connection: Upgrade" \
  --header "Upgrade: websocket" \
  --header "Sec-WebSocket-Version: 13" \
  --header "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  https://echo.websocket.org
Enter fullscreen mode Exit fullscreen mode

Qué revisar:

  • --include muestra los headers de respuesta.
  • Debes ver HTTP/1.1 101 Switching Protocols.
  • --no-buffer evita que curl retenga la salida, algo importante en conexiones de streaming.

Para conexiones seguras, usa wss:// del mismo modo que usarías https://.

curl es útil para una comprobación rápida:

curl --include --no-buffer wss://example.com/socket
Enter fullscreen mode Exit fullscreen mode

Úsalo para responder preguntas como:

  • ¿El endpoint existe?
  • ¿El servidor acepta el upgrade?
  • ¿La autenticación falla antes del handshake?
  • ¿La ruta devuelve 404, 401, 403 o 101?

Pero para sesiones interactivas con varios mensajes, curl no es la opción más cómoda. Si quieres integrar este tipo de comprobaciones en una pipeline, revisa cómo automatizar pruebas de API en CI/CD.

Probando WebSocket con websocat

websocat es una herramienta de línea de comandos diseñada específicamente para WebSocket. Funciona como un netcat para conexiones ws:// y wss://.

Instalación en macOS:

brew install websocat
Enter fullscreen mode Exit fullscreen mode

Instalación con Cargo:

cargo install websocat
Enter fullscreen mode Exit fullscreen mode

Conectarte a un endpoint echo:

websocat wss://echo.websocket.org
Enter fullscreen mode Exit fullscreen mode

Esto abre una sesión interactiva. Escribe un mensaje, presiona Enter y verás la respuesta del servidor.

Ejemplo:

hello
hello
Enter fullscreen mode Exit fullscreen mode

Enviar un solo mensaje y salir

Para enviar un mensaje desde un script:

echo '{"action":"subscribe","channel":"prices"}' | websocat wss://stream.example.com/feed
Enter fullscreen mode Exit fullscreen mode

Esto sirve para pruebas simples de request/response.

Enviar headers de autenticación

Muchos endpoints WebSocket requieren tokens en headers:

websocat \
  --header "Authorization: Bearer your-token-here" \
  wss://api.example.com/socket
Enter fullscreen mode Exit fullscreen mode

También puedes usar parámetros de consulta si tu API los requiere:

websocat "wss://api.example.com/socket?token=your-token-here"
Enter fullscreen mode Exit fullscreen mode

Probar mensajes JSON

Puedes enviar JSON directamente:

websocat wss://api.example.com/socket
Enter fullscreen mode Exit fullscreen mode

Luego escribe:

{"action":"subscribe","channel":"orders"}
Enter fullscreen mode Exit fullscreen mode

Si el servidor responde correctamente, deberías ver algo como:

{"type":"subscribed","channel":"orders"}
Enter fullscreen mode Exit fullscreen mode

Usar websocat en scripts

Un patrón básico para automatizar una comprobación:

response=$(echo '{"type":"ping"}' | websocat -1 wss://api.example.com/socket)

echo "$response"

if echo "$response" | grep -q '"type":"pong"'; then
  echo "WebSocket OK"
  exit 0
else
  echo "WebSocket failed"
  exit 1
fi
Enter fullscreen mode Exit fullscreen mode

websocat cubre la mayoría de los casos que curl no maneja bien: sesiones interactivas, headers personalizados, entrada por stdin, salida por stdout y pruebas automatizadas.

Para validar payloads de forma consistente, las ideas de aserciones de API útiles también aplican a mensajes WebSocket.

Probando WebSocket con una herramienta GUI

La línea de comandos es ideal para scripts, CI y comprobaciones rápidas. Pero para pruebas exploratorias, una GUI suele ser más eficiente.

Usa una GUI cuando necesitas:

  • Ver una línea de tiempo de mensajes enviados y recibidos.
  • Enviar JSON estructurado sin escribir todo en la terminal.
  • Mantener una conexión abierta mientras pruebas distintos mensajes.
  • Configurar headers, query params o tokens de autenticación.
  • Compartir una prueba reproducible con otro desarrollador.

Apidog incluye un cliente WebSocket dedicado. Puedes ingresar una URL ws:// o wss://, conectarte y ver cada mensaje en una línea de tiempo con resaltado JSON. También puedes guardar conexiones, configurar headers y parámetros de consulta, y probar WebSocket junto con REST, GraphQL y SOAP en la misma aplicación.

Puedes descargar Apidog para probar endpoints WebSocket con una vista visual de mensajes.

Como regla práctica:

  • Usa curl para confirmar accesibilidad y handshake.
  • Usa websocat para pruebas técnicas desde terminal.
  • Usa una GUI para exploración, depuración visual y colaboración.

Si quieres comparar opciones, este resumen de herramientas gratuitas de prueba de API en línea incluye alternativas que manejan WebSocket.

Lista de verificación para probar WebSocket

Usa esta checklist cuando pruebes un endpoint WebSocket.

1. Confirma el upgrade

La conexión debe devolver:

HTTP/1.1 101 Switching Protocols
Enter fullscreen mode Exit fullscreen mode

Si no recibes 101, revisa:

  • URL incorrecta.
  • Ruta incorrecta.
  • Headers faltantes.
  • Autenticación fallida.
  • Proxy o gateway bloqueando el upgrade.

2. Verifica la autenticación

Confirma dónde espera el servidor el token:

Header:

websocat \
  --header "Authorization: Bearer your-token-here" \
  wss://api.example.com/socket
Enter fullscreen mode Exit fullscreen mode

Query param:

websocat "wss://api.example.com/socket?token=your-token-here"
Enter fullscreen mode Exit fullscreen mode

Una conexión que se abre y se cierra inmediatamente suele indicar token inválido, expirado o enviado en el lugar incorrecto.

3. Envía un mensaje conocido

Usa una carga útil válida para tu API:

{"action":"subscribe","channel":"prices"}
Enter fullscreen mode Exit fullscreen mode

Verifica que la respuesta tenga la forma esperada:

{"type":"subscribed","channel":"prices"}
Enter fullscreen mode Exit fullscreen mode

4. Verifica mensajes enviados por el servidor

Después de suscribirte, no envíes nada más. Espera mensajes entrantes:

{"type":"price.updated","symbol":"BTCUSD","price":65000}
Enter fullscreen mode Exit fullscreen mode

Esto valida el comportamiento principal de WebSocket: entrega de eventos sin solicitud adicional.

5. Prueba errores

Envía un mensaje inválido:

{"action":"unknown"}
Enter fullscreen mode Exit fullscreen mode

El servidor debería responder con un error controlado, no cerrar la conexión sin explicación:

{"type":"error","message":"Unsupported action"}
Enter fullscreen mode Exit fullscreen mode

6. Prueba el cierre

Cierra la conexión y revisa el código de cierre.

Códigos comunes:

  • 1000: cierre normal.
  • 1006: cierre anormal sin handshake limpio.
  • 1011: error interno del servidor.

Para organizar estas comprobaciones en un conjunto repetible, la guía sobre cómo construir suites de prueba de API también aplica a flujos WebSocket.

Depurando una conexión WebSocket que no funciona

Cuando una conexión WebSocket falla, revisa estos puntos en orden.

1. Verifica el esquema de la URL

Usa el esquema correcto:

ws://example.com/socket
wss://example.com/socket
Enter fullscreen mode Exit fullscreen mode

ws:// no está cifrado.

wss:// usa TLS.

Si tu aplicación corre sobre HTTPS, los navegadores pueden bloquear conexiones ws:// porque mezclan contenido seguro e inseguro. En producción, usa wss://.

2. Revisa el resultado del handshake

Si no recibes 101, el servidor no aceptó la actualización.

Códigos típicos:

  • 400: headers de upgrade faltantes o mal formados.
  • 401: autenticación requerida.
  • 403: autenticación rechazada o permisos insuficientes.
  • 404: ruta incorrecta.
  • 101: upgrade correcto.

Con curl:

curl --include --no-buffer wss://api.example.com/socket
Enter fullscreen mode Exit fullscreen mode

Con websocat, usa modo verboso si necesitas más detalle:

websocat -v wss://api.example.com/socket
Enter fullscreen mode Exit fullscreen mode

3. Revisa timeouts y ping/pong

Si el handshake funciona pero la conexión se cierra segundos después, puede ser por inactividad.

Muchos servidores esperan frames ping/pong para confirmar que el cliente sigue vivo. También puede haber un proxy o balanceador de carga cerrando conexiones inactivas.

Revisa:

  • Timeout del servidor.
  • Timeout del proxy.
  • Configuración del load balancer.
  • Reglas de idle timeout.
  • Si el cliente responde a ping/pong.

4. Lee el código de cierre

Los códigos de cierre están definidos en RFC 6455.

Ejemplos:

  • 1000: cierre normal.
  • 1001: endpoint se va.
  • 1002: error de protocolo.
  • 1003: tipo de datos no soportado.
  • 1006: cierre anormal.
  • 1011: error interno del servidor.

El código de cierre suele indicar si el problema está en el cliente, el servidor, la red o la autenticación.

Automatizando comprobaciones WebSocket

Una prueba manual confirma que el endpoint funciona ahora. Para evitar regresiones, necesitas ejecutarla de forma automática.

Un flujo mínimo automatizado debería validar:

  1. La conexión se actualiza a WebSocket.
  2. Un mensaje conocido recibe la respuesta esperada.
  3. Una suscripción recibe al menos un evento dentro de un timeout.
  4. La prueba falla con código distinto de cero si algo no coincide.

Ejemplo simple con websocat:

#!/usr/bin/env bash

set -euo pipefail

URL="wss://api.example.com/socket"
MESSAGE='{"type":"ping"}'
EXPECTED='"type":"pong"'

response=$(echo "$MESSAGE" | websocat -1 "$URL")

echo "Response: $response"

if echo "$response" | grep -q "$EXPECTED"; then
  echo "WebSocket check passed"
else
  echo "WebSocket check failed"
  exit 1
fi
Enter fullscreen mode Exit fullscreen mode

Ese script puede ejecutarse en CI como cualquier otro paso:

./test-websocket.sh
Enter fullscreen mode Exit fullscreen mode

Mantén estas pruebas enfocadas. No intentes validar todos los mensajes posibles de una conexión larga. Es mejor tener pruebas pequeñas y estables:

  • Una prueba para handshake.
  • Una prueba para autenticación.
  • Una prueba para request/response.
  • Una prueba para suscripción.
  • Una prueba para error controlado.

La misma disciplina que mantiene claro un caso de prueba también mantiene fiables las comprobaciones WebSocket: prueba una cosa específica y hazla verificable.

Preguntas frecuentes

¿Puede curl probar conexiones WebSocket?

Parcialmente. curl 7.86 y posteriores tiene soporte experimental para WebSocket. Sirve para comprobar si un endpoint es accesible y si el handshake se completa. Para sesiones interactivas con muchos mensajes, websocat o una GUI como Apidog son mejores opciones.

¿Cuál es la diferencia entre ws y wss?

ws:// es WebSocket sin cifrado.

wss:// es WebSocket cifrado con TLS.

Es la misma diferencia práctica que entre HTTP y HTTPS. Usa wss:// fuera del desarrollo local, porque ws:// envía mensajes en texto plano.

¿Por qué mi conexión WebSocket se abre y luego se cierra inmediatamente?

La causa más común es autenticación fallida. El servidor puede aceptar la conexión TCP y luego cerrarla si el token falta, expiró o está en el lugar incorrecto.

Revisa:

  • Header Authorization.
  • Parámetros de consulta.
  • Expiración del token.
  • Código de cierre.
  • Logs del servidor.

¿Es websocat mejor que curl para probar WebSocket?

Sí, para WebSocket específicamente. websocat está diseñado para este protocolo, soporta sesiones interactivas, headers personalizados, redirección de entrada/salida y manejo correcto de tramas. Usa curl para comprobaciones rápidas y websocat para pruebas reales desde terminal.

¿Cómo pruebo que un servidor envía mensajes sin una solicitud?

Abre la conexión, suscríbete al canal o evento requerido y espera sin enviar más mensajes.

Con websocat:

websocat wss://api.example.com/socket
Enter fullscreen mode Exit fullscreen mode

Envía:

{"action":"subscribe","channel":"orders"}
Enter fullscreen mode Exit fullscreen mode

Luego observa si llegan eventos sin más entrada:

{"type":"order.created","id":"ord_123"}
Enter fullscreen mode Exit fullscreen mode

Con una GUI como Apidog, esos mensajes aparecen en la línea de tiempo de la conexión.

Top comments (0)