WebSocket은 단일 TCP 연결을 통해 클라이언트와 서버 간에 지속적인 양방향 채널을 제공합니다. 연결이 열리면 양쪽에서 언제든지 메시지를 보낼 수 있으며, 이것이 라이브 채팅, 거래 피드, 멀티플레이어 게임 및 대시보드의 중추를 이룹니다. 이를 테스트하는 것은 요청-응답 API를 테스트하는 것과는 다른 작업입니다. 검사할 단일 응답이 없기 때문입니다. 이는 스트림입니다.
이 가이드는 실용적입니다. curl이 WebSocket으로 할 수 있는 것과 할 수 없는 것, 전용 도구인 websocat을 사용하는 방법, 그리고 GUI 클라이언트가 더 나은 선택인 경우를 다룹니다. 여기에 있는 모든 명령은 실제이며 복사하여 바로 사용할 수 있습니다.
WebSocket 테스트가 REST 테스트와 다른 이유
REST 테스트는 트랜잭션입니다. 하나의 요청을 보내고, 하나의 응답을 받고, 그것을 확인하면 완료됩니다. 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을 통해 설치할 수 있습니다. 그런 다음 연결하고 채팅하는 것은 하나의 명령으로 가능합니다:
websocat wss://echo.websocket.org
이는 대화형 세션을 엽니다. 한 줄을 입력하고 Enter를 누르면 메시지가 전송됩니다. 서버의 응답은 도착하는 대로 출력됩니다. 단일 메시지를 보내고 종료하려면 파이프를 통해 입력합니다:
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 작업과 함께 진행됩니다. 시각적 타임라인으로 WebSocket 엔드포인트를 테스트하려면 Apidog를 다운로드하십시오.
익숙하지 않은 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의 자세한 모드 모두 이 응답을 표시하여 핸드셰이크 실패와 나중의 문제를 구분할 수 있게 합니다.
핸드셰이크는 성공했지만 몇 초 후에 연결이 끊어진다면 유휴 시간 초과 및 핑 또는 퐁 프레임을 확인하십시오. 많은 서버는 클라이언트가 여전히 살아 있음을 증명하기 위해 핑 프레임에 응답하기를 기대하며, 조용해지는 연결은 끊어 버립니다. 서버 앞의 프록시 또는 로드 밸런서도 자체 스케줄에 따라 유휴 연결을 끊을 수 있습니다. 마지막으로 종료 코드를 읽으십시오. 코드는 RFC 6455에 정의되어 있으며, 1006과 같은 코드는 깨끗한 핸드셰이크가 없는 비정상적인 종료를 나타내고, 1011은 서버 오류를 나타냅니다. 종료 코드는 일반적으로 어느 쪽이 포기했는지, 그리고 그 이유를 알려줍니다.
WebSocket 확인 자동화
일회성 수동 테스트는 오늘 엔드포인트가 작동함을 확인합니다. 그러나 다음 주에 발생할 수 있는 회귀로부터 보호하지는 않습니다. 이를 위해서는 WebSocket 확인이 무인으로 실행되어야 합니다.
명령줄 도구를 사용하면 이것이 간단해집니다. 작은 스크립트가 websocat으로 연결을 열고, 알려진 메시지를 보내고, 응답을 캡처하고, 예상 값과 비교한 다음, 일치하지 않으면 0이 아닌 값으로 종료할 수 있습니다. 이 스크립트는 다른 테스트 단계처럼 CI 파이프라인에 통합됩니다. Apidog와 같은 시나리오 러너가 있는 GUI 도구는 보낸 메시지와 응답에 대한 어설션을 포함하는 WebSocket 흐름을 저장하고, 일정에 따라 또는 파이프라인 트리거에서 재생할 수 있습니다.
자동화된 WebSocket 테스트를 집중적으로 유지하십시오. 연결이 업그레이드되는지 확인하고, 하나의 알려진 요청-응답 쌍을 확인하고, 구독한 채널이 시간 초과 내에 최소 하나의 푸시 메시지를 전달하는지 확인하십시오. 오래 지속되는 연결의 가능한 모든 메시지를 확인하려고 하면 테스트가 느려지고 불안정해집니다. 테스트 케이스를 날카롭게 유지하는 것과 동일한 절제가 WebSocket 확인을 신뢰할 수 있게 만듭니다: 하나의 명확한 것을 테스트하고, 그것을 잘 테스트하십시오.
자주 묻는 질문
curl로 WebSocket 연결을 테스트할 수 있습니까?
부분적으로 가능합니다. curl 7.86 이상에는 핸드셰이크를 완료하고 기본 메시지를 교환할 수 있는 실험적인 네이티브 WebSocket 지원이 있습니다. 이는 엔드포인트에 도달할 수 있는지 확인하기에 충분합니다. 하지만 많은 메시지를 주고받는 대화형 세션에는 어색합니다. 실제 WebSocket 테스트에는 websocat 또는 Apidog와 같은 GUI 클라이언트가 더 적합합니다.
ws와 wss의 차이점은 무엇입니까?
ws://는 암호화되지 않은 WebSocket 연결이며, wss://는 TLS로 암호화된 연결입니다. 이는 HTTP 대 HTTPS의 WebSocket 버전과 같습니다. 로컬 개발 환경을 넘어선 모든 경우에는 항상 wss://를 사용하십시오. ws://는 메시지를 일반 텍스트로 보내기 때문입니다. 도구는 암호화 여부를 제외하고 두 URL을 동일하게 처리합니다.
내 WebSocket 연결이 열렸다가 즉시 닫히는 이유는 무엇입니까?
가장 흔한 원인은 인증입니다. 서버가 헤더나 쿼리 매개변수에 토큰을 기대하지만 유효한 토큰을 받지 못하면 TCP 연결을 수락한 다음 닫습니다. 종료 코드를 확인하고, 토큰이 유효한지 확인하며, 서버가 예상하는 방식으로 토큰을 보내고 있는지 확인하십시오.
WebSocket 테스트에 websocat이 curl보다 낫습니까?
WebSocket에 관해서는 그렇습니다. websocat은 목적에 맞게 구축되었으며, 프레임 프로토콜을 완전히 이해하고, 대화형 세션, 사용자 지정 헤더, 메시지 입출력 파이프를 지원합니다. curl은 WebSocket 지원이 아직 실험적인 일반 HTTP 도구입니다. 빠른 연결 가능성 확인에는 curl을 사용하고, 실제 테스트에는 websocat을 사용하십시오.
서버가 요청 없이 메시지를 푸시하는지 어떻게 테스트합니까?
연결을 열고, API에서 요구하는 경우 관련 채널 또는 이벤트를 구독한 다음, 기다리면서 지켜보십시오. websocat에서는 푸시된 메시지가 도착하는 대로 출력됩니다. Apidog와 같은 GUI 클라이언트에서는 메시지 타임라인에 나타납니다. WebSocket의 핵심은 요청하지 않은 메시지 전달이므로, 추가 입력 없이 메시지가 도착하는지 확인하십시오.