WebSocket oferece um canal persistente e bidirecional entre cliente e servidor através de uma única conexão TCP. Uma vez que a conexão está aberta, qualquer lado pode enviar uma mensagem a qualquer momento, o que a torna a espinha dorsal de chats ao vivo, feeds de negociação, jogos multiplayer e painéis de controle. Testá-lo é um exercício diferente de testar uma API de solicitação-resposta, porque não há uma única resposta para inspecionar. Há um fluxo.
Este guia é prático. Ele aborda o que o curl pode e não pode fazer com WebSocket, como usar a ferramenta dedicada websocat e quando um cliente GUI é a melhor escolha. Cada comando aqui é real e pronto para copiar.
Por que o teste de WebSocket não é como o teste de REST
Um teste REST é uma transação. Você envia uma solicitação, recebe uma resposta, faz asserções sobre ela e pronto. Um teste WebSocket é uma conversa. Você abre uma conexão uma vez, depois troca muitas mensagens ao longo de sua vida útil, e as mensagens podem chegar sem que você as solicite.
Isso muda o que você verifica. Você confirma que a conexão é atualizada corretamente do HTTP. Você confirma que o servidor aceita sua primeira mensagem e responde como esperado. Você confirma que as mensagens enviadas pelo servidor chegam sem que você as solicite. Você observa como a conexão é fechada e com qual código de fechamento. Uma ferramenta construída para solicitações únicas tem dificuldades com tudo isso, e é por isso que o curl, a ferramenta HTTP universal, é apenas parcialmente adequado. Para um panorama de teste mais amplo, a diferença entre um cenário de teste e um caso de teste se mapeia perfeitamente em uma conversa WebSocket versus uma verificação de mensagem única.
O handshake WebSocket
Toda conexão WebSocket começa como uma solicitação HTTP que pede para ser atualizada. O cliente envia os cabeçalhos Upgrade: websocket e Connection: Upgrade, além de um Sec-WebSocket-Key, e o servidor responde com HTTP 101 Switching Protocols. Depois disso, a conexão não é mais HTTP. Ela fala o protocolo de frames WebSocket definido na RFC 6455.
Esta é a raiz da limitação do curl. O curl clássico fala HTTP. Ele pode enviar os cabeçalhos de upgrade, mas não pode enquadrar e desenquadrar mensagens WebSocket após o handshake. Tentar simular uma sessão WebSocket completa com flags de cabeçalho brutos não funciona além do próprio handshake. Você precisa de uma ferramenta que entenda frames.
Testando WebSocket com curl
O curl moderno, versão 7.86 e posterior, adicionou suporte nativo experimental para WebSocket. É genuinamente utilizável para verificações simples, com a ressalva de que ainda é marcado como experimental.
Primeiro, confirme sua versão:
curl --version
Se você estiver na versão 7.86 ou mais recente, pode se conectar a um endpoint WebSocket diretamente. Aqui está uma conexão a um servidor de eco público, que responde com o que você enviar:
curl --include --no-buffer \
--header "Connection: Upgrade" \
--header "Upgrade: websocket" \
--header "Sec-WebSocket-Version: 13" \
--header "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
https://echo.websocket.org
A flag --include mostra os cabeçalhos de resposta para que você possa confirmar o status 101, e --no-buffer impede que o curl retenha a saída, o que é importante para um fluxo. Para conexões seguras, use um URL wss:// exatamente como usaria https://.
O suporte a WebSocket do curl brilha em uma coisa: confirmar que um endpoint é acessível e completa o upgrade. É desajeitado para uma sessão interativa onde você envia várias mensagens e lê as respostas, porque o curl não é construído em torno de um loop de mensagens. Para uma verificação rápida de "este endpoint está vivo" em um script, é bom. Para testes interativos reais, procure uma ferramenta dedicada. Se você estiver roteirizando essas verificações em um pipeline, nosso guia sobre automação de testes de API em CI/CD cobre como conectar verificações de linha de comando em um build.
Testando WebSocket com websocat
websocat é a ferramenta de linha de comando que a maioria das pessoas realmente deseja para trabalhar com WebSocket. É construída propositalmente, entende frames corretamente e se comporta como um netcat para WebSocket.
Instale-o com seu gerenciador de pacotes, por exemplo brew install websocat no macOS ou via cargo install websocat. Em seguida, conectar e conversar é um único comando:
websocat wss://echo.websocket.org
Isso abre uma sessão interativa. Digite uma linha, pressione enter, e ela é enviada como uma mensagem. As respostas do servidor são impressas à medida que chegam. Para enviar uma única mensagem e sair, use um pipe:
echo '{"action":"subscribe","channel":"prices"}' | websocat wss://stream.example.com/feed
websocat também lida com extras úteis. Você pode passar cabeçalhos para endpoints autenticados:
websocat --header "Authorization: Bearer seu-token-aqui" wss://api.example.com/socket
E você pode executá-lo como um servidor local para testar um cliente, ou fazer a ponte de um WebSocket para uma porta TCP simples. Para testes de WebSocket por linha de comando, websocat cobre quase tudo o que o curl não consegue. Trate as asserções da mesma forma que faria em outro lugar; nossas notas sobre escrever asserções de API úteis também se aplicam à verificação de payloads de mensagens.
Testando WebSocket com uma ferramenta GUI
Ferramentas de linha de comando são ótimas para scripts e verificações rápidas. Elas são cansativas para testes exploratórios, onde você quer ver a linha do tempo das mensagens, enviar JSON estruturado confortavelmente e manter uma conexão aberta enquanto você a investiga.
Apidog possui um cliente WebSocket dedicado construído para isso. Você insere um URL ws:// ou wss://, conecta-se e vê cada mensagem enviada e recebida em uma visualização de linha do tempo com realce de sintaxe JSON. Você pode salvar conexões, definir cabeçalhos e parâmetros de consulta para autenticação e manter a conexão ativa enquanto experimenta. Ele lida com REST, GraphQL e SOAP no mesmo aplicativo, então o teste de WebSocket se encaixa ao lado do restante do seu trabalho de API, em vez de em uma ferramenta separada. Baixe o Apidog para testar endpoints WebSocket com uma linha do tempo visual.
Uma GUI é a escolha certa quando você está explorando uma API WebSocket desconhecida, depurando por que as mensagens não estão chegando ou compartilhando um teste reproduzível com um colega de equipe. A linha de comando é a escolha certa quando você quer que a verificação seja executada sem supervisão. A maioria dos engenheiros usa ambos, escolhendo pela tarefa. Se você quiser uma visão mais ampla das opções de GUI, nossa lista de ferramentas de teste de API online gratuitas inclui várias que lidam com WebSocket.
Uma lista de verificação simples para testes WebSocket
- Confirme o upgrade. A conexão deve retornar HTTP 101. Se não retornar, o endpoint, o caminho ou seus cabeçalhos estão incorretos.
- Verifique a autenticação. Muitos servidores WebSocket esperam um token em um cabeçalho ou parâmetro de consulta. Uma conexão que abre e fecha imediatamente geralmente significa um token rejeitado.
- Envie uma mensagem conhecida e verifique a resposta. Use um payload real que sua API entenda e confirme o formato da resposta.
- Verifique as mensagens enviadas pelo servidor. Assine um canal e confirme que as atualizações chegam sem mais solicitações de sua parte.
- Teste o fechamento. Feche a conexão e verifique o código de fechamento. Um fechamento limpo é 1000; outros códigos sinalizam problemas específicos.
- Teste os caminhos de falha. Envie uma mensagem malformada e confirme que o servidor responde de forma sensata, em vez de cair silenciosamente.
Para organizar esses itens em um conjunto repetível, nosso guia sobre construção de suites de teste de API se aplica a fluxos WebSocket tanto quanto a REST.
Depurando uma conexão WebSocket que não funciona
Quando uma conexão WebSocket falha, a causa é quase sempre um pequeno conjunto de problemas. Verifique-os em ordem.
Comece com o esquema do URL. Uma conexão para wss:// de uma página ou contexto que espera ws://, ou o contrário, falha imediatamente. Os navegadores também bloqueiam uma conexão ws:// de uma página servida via HTTPS, pois isso mistura conteúdo seguro e inseguro. Confirme se o esquema corresponde ao ambiente.
Em seguida, verifique a resposta do handshake. Se você não vir HTTP 101, o servidor nunca concordou em fazer o upgrade. Um 404 significa que o caminho está errado. Um 401 ou 403 significa que a autenticação falhou antes do upgrade. Um 400 geralmente significa um cabeçalho de upgrade ausente ou malformado. A flag --include do curl e o modo verboso do websocat mostram essa resposta, para que você possa diferenciar uma falha de handshake de um problema posterior.
Se o handshake for bem-sucedido, mas a conexão cair segundos depois, procure por timeouts de inatividade e frames de ping ou pong. Muitos servidores esperam que o cliente responda a frames de ping para provar que ainda está ativo, e eles fecham as conexões que ficam em silêncio. Um proxy ou balanceador de carga na frente do servidor também pode encerrar conexões ociosas em seu próprio cronograma. Finalmente, leia o código de fechamento. Os códigos são definidos na RFC 6455, e um código como 1006 aponta para um fechamento anormal sem handshake limpo, enquanto 1011 sinaliza um erro de servidor. O código de fechamento geralmente diz qual lado desistiu e por quê.
Automatizando verificações WebSocket
Um teste manual avulso confirma que um endpoint funciona hoje. Ele não o protege de uma regressão na próxima semana. Para isso, a verificação WebSocket precisa ser executada sem supervisão.
As ferramentas de linha de comando tornam isso direto. Um pequeno script pode abrir uma conexão com websocat, enviar uma mensagem conhecida, capturar a resposta e compará-la com um valor esperado, e então sair com um código diferente de zero se não corresponder. Esse script se encaixa em um pipeline de CI como qualquer outra etapa de teste. Uma ferramenta GUI com um executor de cenários, como o Apidog, pode salvar um fluxo WebSocket, incluindo as mensagens enviadas e as asserções nas respostas, e reproduzi-lo em um cronograma ou a partir de um gatilho de pipeline.
Mantenha os testes automatizados de WebSocket focados. Afirme que a conexão é atualizada, afirme um par conhecido de solicitação e resposta, e afirme que um canal inscrito entrega pelo menos uma mensagem "push" dentro de um tempo limite. Tentar afirmar cada mensagem possível de uma conexão de longa duração torna o teste lento e instável. A mesma restrição que mantém um caso de teste afiado mantém uma verificação WebSocket confiável: teste uma coisa clara e teste-a bem.
Perguntas frequentes
O curl pode testar conexões WebSocket?
Parcialmente. O curl 7.86 e versões posteriores possuem suporte nativo experimental a WebSocket que pode completar o handshake e trocar mensagens básicas, o que é suficiente para confirmar que um endpoint é acessível. É desajeitado para sessões interativas com muitas mensagens. Para testes WebSocket reais, o websocat ou um cliente GUI como o Apidog é uma opção melhor.
Qual a diferença entre ws e wss?
ws:// é uma conexão WebSocket não criptografada, e wss:// é criptografada com TLS, o equivalente WebSocket de HTTP versus HTTPS. Sempre use wss:// para qualquer coisa além de desenvolvimento local, já que ws:// envia mensagens em texto simples. As ferramentas tratam os dois URLs de forma idêntica, exceto pela criptografia.
Por que minha conexão WebSocket abre e depois fecha imediatamente?
A causa mais comum é a autenticação. Se o servidor espera um token em um cabeçalho ou parâmetro de consulta e não recebe um válido, ele aceita a conexão TCP e depois a fecha. Verifique o código de fechamento, valide seu token e confirme se você o está enviando da maneira que o servidor espera.
O websocat é melhor que o curl para testes WebSocket?
Para WebSocket especificamente, sim. websocat é construído para esse propósito, entende o protocolo de frames completamente, suporta sessões interativas, cabeçalhos personalizados e pipe de mensagens de entrada e saída. curl é uma ferramenta HTTP geral cujo suporte a WebSocket ainda é experimental. Use curl para uma verificação rápida de acessibilidade e websocat para testes reais.
Como testar se um servidor envia mensagens sem uma solicitação?
Abra a conexão, inscreva-se no canal ou evento relevante, se a API exigir, e então espere e observe. Com o websocat, as mensagens enviadas são impressas à medida que chegam. Com um cliente GUI como o Apidog, elas aparecem na linha do tempo das mensagens. Confirme se as mensagens chegam sem qualquer outra entrada sua, já que a entrega não solicitada é o objetivo do WebSocket.