WebSocketは、単一のTCP接続を介してクライアントとサーバー間の永続的な双方向チャネルを提供します。接続が確立されると、どちらの側もいつでもメッセージを送信できるため、ライブチャット、取引フィード、マルチプレイヤーゲーム、ダッシュボードのバックボーンとなっています。リクエスト-レスポンスAPIのテストとは異なり、単一のレスポンスを検査するのではなく、ストリームであるため、そのテストは異なる作業となります。
このガイドは実践的です。curlがWebSocketでできることとできないこと、専用ツールwebsocatの使い方、そしてGUIクライアントがより良い選択となる場合について説明します。ここにあるすべてのコマンドは実際のコマンドであり、すぐにコピーして使えます。
WebSocketのテストがRESTテストと異なる理由
RESTテストはトランザクションです。1つのリクエストを送信し、1つのレスポンスを受け取り、それをアサートして完了です。WebSocketテストは会話です。接続を一度確立し、その有効期間中に多くのメッセージを交換します。そしてメッセージは、要求なしに到着することもあります。
それが確認する内容を変えます。接続がHTTPから正しくアップグレードされたことを確認します。サーバーが最初のメッセージを受け入れ、期待どおりに返信することを確認します。サーバープッシュされたメッセージが、要求なしに到着することを確認します。接続がどのように閉じられ、どのクローズコードで閉じられたかを監視します。単発のリクエスト向けに作られたツールはこれらすべてに苦労するため、普遍的なHTTPツールであるcurlも部分的にしか適していません。より広範なテストの観点から見ると、テストシナリオとテストケースの違いは、WebSocketの会話と単一メッセージのチェックにきれいに当てはまります。
WebSocketハンドシェイク
すべてのWebSocket接続は、アップグレードを要求するHTTPリクエストとして開始されます。クライアントはUpgrade: websocketとConnection: Upgradeヘッダー、さらにSec-WebSocket-Keyを送信し、サーバーはHTTP 101 Switching Protocolsで応答します。その後、接続はもはやHTTPではありません。RFC 6455で定義されたWebSocketフレームプロトコルを話します。
これがcurlの限界の根源です。従来のcurlはHTTPを話します。アップグレードヘッダーを送信することはできますが、ハンドシェイク後にWebSocketメッセージをフレーム化したり、フレーム解除したりすることはできません。生のヘッダーフラグを使って完全なWebSocketセッションを偽装しようとしても、ハンドシェイクを超えては機能しません。フレームを理解するツールが必要です。
curlでのWebSocketテスト
最新のcurl、バージョン7.86以降では、実験的なネイティブWebSocketサポートが追加されました。まだ実験的という注意書きはありますが、単純なチェックには実際に使用できます。
まず、バージョンを確認します。
curl --version
バージョン7.86以降であれば、WebSocketエンドポイントに直接接続できます。これはパブリックなエコーサーバーへの接続で、送信した内容をそのまま返します。
curl --include --no-buffer \
--header "Connection: Upgrade" \
--header "Upgrade: websocket" \
--header "Sec-WebSocket-Version: 13" \
--header "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
https://echo.websocket.org
--includeフラグはレスポンスヘッダーを表示し、101ステータスを確認できます。--no-bufferは、ストリームにとって重要な、curlが出力を保持するのを停止します。セキュアな接続には、https://と同じようにwss:// URLを使用します。
curlのWebSocketサポートは、エンドポイントが到達可能でアップグレードを完了することを確認するのに優れています。複数のメッセージを送信し、返信を読み取るインタラクティブなセッションには不向きです。なぜなら、curlはメッセージループを中心に構築されていないからです。スクリプトでの迅速な「このエンドポイントは生きているか」チェックには適しています。実際のインタラクティブなテストには、専用ツールを使用してください。これらのチェックをパイプラインにスクリプト化している場合、CI/CDでAPIテストを自動化するというガイドでは、コマンドラインチェックをビルドに組み込む方法を説明しています。
websocatでのWebSocketテスト
websocatは、ほとんどの人がWebSocket作業で実際に欲しがるコマンドラインツールです。目的のために作られ、フレームを正しく理解し、WebSocket用のnetcatのように動作します。
パッケージマネージャーでインストールします。例えばmacOSではbrew install websocat、またはcargo install websocatでインストールできます。その後、接続してチャットするのは1つのコマンドです。
websocat wss://echo.websocket.org
これによりインタラクティブセッションが開きます。行を入力し、エンターキーを押すと、メッセージとして送信されます。サーバーの返信は到着すると表示されます。単一のメッセージを送信して終了するには、パイプで渡します。
echo '{"action":"subscribe","channel":"prices"}' | websocat wss://stream.example.com/feed
websocatは便利な追加機能も処理します。認証されたエンドポイントにヘッダーを渡すことができます。
websocat --header "Authorization: Bearer your-token-here" wss://api.example.com/socket
また、クライアントをテストするためにローカルサーバーとして実行したり、WebSocketをプレーンなTCPポートにブリッジしたりすることもできます。コマンドラインでのWebSocketテストにおいて、websocatはcurlができないほとんどすべてをカバーします。アサーションは他の場所と同じように扱ってください。有用なAPIアサーションの書き方に関する私たちのメモは、メッセージペイロードのチェックにも適用されます。
GUIツールでのWebSocketテスト
コマンドラインツールはスクリプトや迅速なチェックには優れています。しかし、メッセージのタイムラインを確認し、構造化されたJSONを快適に送信し、接続を維持しながら操作したい探索的テストでは、疲れるものです。
Apidogには、この目的のために構築された専用のWebSocketクライアントがあります。ws://またはwss:// URLを入力して接続すると、JSONシンタックスハイライト付きのタイムラインビューで送受信されたすべてのメッセージが表示されます。接続を保存したり、認証用のヘッダーやクエリパラメータを設定したり、実験中に接続を維持したりできます。REST、GraphQL、SOAPを同じアプリケーションで処理するため、WebSocketテストは別のツールではなく、他のAPI作業と並行して行えます。Apidogをダウンロードして、視覚的なタイムラインでWebSocketエンドポイントをテストしてください。
不慣れなWebSocket APIを探索している場合、メッセージが届かない理由をデバッグしている場合、または再現可能なテストをチームメイトと共有している場合は、GUIが正しい選択です。チェックを自動実行したい場合は、コマンドラインが正しい選択です。ほとんどのエンジニアは、タスクに応じて両方を使い分けます。GUIオプションのより広範なビューが必要な場合は、無料のオンラインAPIテストツールのまとめに、WebSocketを処理できるものがいくつか含まれています。
シンプルなWebSocketテストチェックリスト
- アップグレードを確認する。 接続はHTTP 101を返す必要があります。返さない場合、エンドポイント、パス、またはヘッダーが間違っています。
- 認証を確認する。 多くのWebSocketサーバーは、ヘッダーまたはクエリパラメータにトークンを期待します。接続が開いてすぐに閉じる場合、通常はトークンが拒否されたことを意味します。
- 既知のメッセージを送信し、返信を確認する。 APIが理解する実際のペイロードを使用し、レスポンスの形式を確認します。
- サーバープッシュされたメッセージを確認する。 チャネルを購読し、それ以上の要求なしに更新が届くことを確認します。
- クローズをテストする。 接続を閉じ、クローズコードを確認します。クリーンなクローズは1000です。他のコードは特定の問題を示します。
- 失敗パスをテストする。 形式が不正なメッセージを送信し、サーバーが黙ってドロップするのではなく、適切に応答することを確認します。
これらを再現可能なセットに整理するには、APIテストスイートの構築に関する私たちのガイドが、RESTと同様にWebSocketフローにも適用されます。
機能しないWebSocket接続のデバッグ
WebSocket接続が失敗する場合、原因はほとんど常に少数の問題のいずれかです。それらを順番に解決してください。
まず、URLスキームから始めます。ws://を期待するページまたはコンテキストからwss://への接続、またはその逆の場合、すぐに失敗します。ブラウザは、HTTPSで提供されるページからのws://接続もブロックします。これは安全なコンテンツと安全でないコンテンツが混在するためです。スキームが環境と一致していることを確認してください。
次に、ハンドシェイク応答を確認します。HTTP 101が表示されない場合、サーバーはアップグレードに同意しませんでした。404はパスが間違っていることを意味します。401または403は、アップグレード前に認証が失敗したことを意味します。400は、多くの場合、不足または不正なアップグレードヘッダーを意味します。curlの--includeフラグとwebsocatの冗長モードはどちらもこの応答を表示するため、ハンドシェイクの失敗とそれ以降の問題を区別できます。
ハンドシェイクが成功しても接続が数秒後に切断される場合は、アイドルタイムアウトとpingまたはpongフレームを確認してください。多くのサーバーは、まだ生きていることを証明するためにクライアントがpingフレームに応答することを期待しており、応答のない接続は閉じます。サーバーの前のプロキシまたはロードバランサーも、独自のスケジュールでアイドル接続を切断することがあります。最後に、クローズコードを読み取ってください。コードはRFC 6455で定義されており、1006のようなコードはクリーンなハンドシェイクなしの異常な終了を指し、1011はサーバーエラーを示します。クローズコードは通常、どちらの側がなぜ諦めたかを教えてくれます。
WebSocketチェックの自動化
一度きりの手動テストは、エンドポイントが今日機能していることを確認します。それは来週の回帰から保護するものではありません。そのためには、WebSocketチェックは無人で実行される必要があります。
コマンドラインツールはこれを簡単にします。小さなスクリプトでwebsocatを使用して接続を開き、既知のメッセージを送信し、返信をキャプチャし、期待値と比較し、一致しない場合はゼロ以外のコードで終了できます。このスクリプトは、他のテストステップと同様にCIパイプラインに組み込まれます。Apidogのようなシナリオランナーを持つGUIツールは、送信されたメッセージや返信に対するアサーションを含むWebSocketフローを保存し、スケジュールまたはパイプライントリガーでそれを再生できます。
自動化されたWebSocketテストは焦点を絞って行います。接続がアップグレードされること、既知のリクエストとレスポンスのペアが1つあること、そして購読したチャネルがタイムアウト内に少なくとも1つのプッシュメッセージを配信することを確認します。長期間の接続で可能なすべてのメッセージをアサートしようとすると、テストが遅くなり不安定になります。テストケースをシャープに保つのと同じ抑制が、WebSocketチェックを信頼できるものに保ちます。つまり、1つの明確なことをテストし、それを適切にテストするのです。
よくある質問
curlはWebSocket接続をテストできますか？
部分的に可能です。curl 7.86以降は実験的なネイティブWebSocketサポートを備えており、ハンドシェイクを完了し、基本的なメッセージを交換できます。これはエンドポイントが到達可能であることを確認するのに十分です。多数のメッセージを含むインタラクティブなセッションには不向きです。実際のWebSocketテストには、websocatまたはApidogのようなGUIクライアントがより適しています。
wsとwssの違いは何ですか？
ws://は暗号化されていないWebSocket接続であり、wss://はTLSで暗号化されており、HTTPとHTTPSのWebSocket版です。ws://はプレーンテキストでメッセージを送信するため、ローカル開発以外では常にwss://を使用してください。ツールは暗号化以外は両方のURLを同じように扱います。
WebSocket接続が開いてすぐに閉じるのはなぜですか？
最も一般的な原因は認証です。サーバーがヘッダーまたはクエリパラメータにトークンを期待し、有効なトークンを受け取らない場合、TCP接続を受け入れてから閉じます。クローズコードを確認し、トークンが正しいことを確認し、サーバーが期待する形式で送信していることを確認してください。
WebSocketテストではwebsocatの方がcurlよりも優れていますか？
WebSocketに特化して言えば、はい。websocatは目的のために作られており、フレームプロトコルを完全に理解し、インタラクティブセッション、カスタムヘッダー、メッセージの入出力をサポートしています。curlは汎用HTTPツールであり、WebSocketサポートはまだ実験段階です。迅速な到達可能性チェックにはcurlを使用し、実際のテストにはwebsocatを使用してください。
サーバーがリクエストなしでメッセージをプッシュすることを確認するにはどうすればよいですか？
接続を開き、APIが必要とする場合は関連するチャネルまたはイベントを購読し、その後待機して監視します。websocatを使用すると、プッシュされたメッセージは到着すると表示されます。ApidogのようなGUIクライアントを使用すると、メッセージタイムラインに表示されます。自らの入力なしにメッセージが届くことを確認してください。なぜなら、非要求型配信がWebSocketの目的だからです。