Insomnia는 Kong이 요청 전송 및 응답 검사를 위해 개발한 API 클라이언트입니다. 깔끔하고 방해 없는 인터페이스와 HTTP, REST, GraphQL, gRPC, SOAP, WebSocket을 한 곳에서 지원하는 것으로 잘 알려져 있습니다. 개발자들은 무거운 IDE 스타일 도구보다 가볍지만 실제 테스트 작업을 수행할 수 있는 도구를 원할 때 Insomnia를 찾습니다.
이 가이드에서는 Insomnia에서 API를 처음부터 끝까지 테스트하는 방법을 보여줍니다. 요청 컬렉션을 생성하고, 응답을 보내고 검사하며, 기본 URL과 토큰을 전환할 수 있도록 환경을 설정하고, 테스트 스위트 기능을 사용하여 자동으로 실행되는 어설션을 작성할 것입니다. 예제는 공개 API를 사용하므로 즉시 따라 할 수 있습니다.
Insomnia 설치 및 요청 생성
Kong 공식 사이트에서 Insomnia를 다운로드하여 플랫폼에 설치하십시오. 처음 실행할 때 Insomnia는 로그인할지 묻습니다. 원한다면 계정 없이 로컬에서 작업할 수 있으며, Insomnia는 데이터를 사용자 컴퓨터에 저장합니다. 클라우드 동기화는 선택 사항이며, 버전 8에서 변경된 사항이며 아래에서 다룰 것입니다.
Insomnia는 작업을 컬렉션과 문서로 구성합니다. 대시보드에서 생성을 클릭하고 요청 컬렉션을 선택합니다. "사용자 API 테스트"와 같이 명확한 이름을 지정합니다. 컬렉션 내에서 + 버튼을 클릭하고 HTTP 요청을 선택합니다.
요청에는 메서드와 URL이 필요합니다. GET을 선택하고 실제 엔드포인트를 입력합니다. JSONPlaceholder 서비스는 연습용으로 잘 작동합니다.
GET https://jsonplaceholder.typicode.com/users/1
전송을 클릭합니다. 오른쪽 창에는 응답 본문, 상태 코드, 응답 시간 및 크기가 표시됩니다. Insomnia는 JSON을 자동으로 예쁘게 출력하며, 응답이 클 때 유용한 JSONPath 또는 XPath 쿼리로 본문을 필터링할 수 있습니다.
메서드, 매개변수 및 인증 구성
간단한 읽기 이상의 작업에는 요청에 더 많은 설정을 해야 합니다. Insomnia는 이들을 URL 바 아래의 탭으로 그룹화합니다.
본문 탭은 요청 페이로드를 처리합니다. POST의 경우 JSON을 선택하고 데이터를 입력합니다.
{
"name": "Daniel Okafor",
"email": "daniel.okafor@example.com"
}
본문 유형을 선택하면 Insomnia가 Content-Type 헤더를 자동으로 설정합니다. 쿼리 탭을 사용하면 URL을 수동으로 편집하지 않고도 쿼리 문자열 매개변수를 추가할 수 있어 긴 URL을 읽기 쉽게 유지하고 개별 매개변수를 켜고 끌 수 있습니다. 헤더 탭은 사용자 정의 X-Request-Id 또는 응답 형식을 협상하기 위한 Accept 헤더와 같이 API가 기대하는 다른 모든 것에 사용됩니다.
인증 탭은 자격 증명을 처리합니다. Insomnia는 Bearer Token, Basic Auth, API Key, OAuth 1.0 및 2.0, AWS IAM 등 다양한 체계를 지원합니다. API가 사용하는 체계를 선택하고 필드를 채웁니다. 토큰으로 보호되는 API의 경우 Bearer Token을 선택하고 토큰을 붙여넣거나, 더 나은 방법으로는 환경 변수를 참조하여 토큰이 하드코딩되지 않도록 합니다. 어떤 상태 코드를 예상해야 할지 확실하지 않다면 REST API가 사용해야 할 HTTP 상태 코드에 대한 참조가 좋은 참고 자료가 될 것입니다.
환경 및 변수 설정
환경을 사용하면 값 반복을 피하고 대상을 쉽게 전환할 수 있습니다. Insomnia에서 환경은 컬렉션에 첨부된 변수들의 JSON 객체입니다.
사이드바 상단 근처의 환경 드롭다운을 클릭하고 환경 관리를 엽니다. 기본 환경은 공유 값을 저장합니다. 각 대상에 대한 하위 환경을 추가합니다.
{
"base_url": "https://jsonplaceholder.typicode.com",
"auth_token": "your-token-here"
}
다른 값으로 프로덕션용 두 번째 하위 환경을 만듭니다. 템플릿 구문 {{ _.base_url }}을 사용하여 모든 요청에서 변수를 참조하면 URL은 다음과 같이 됩니다.
GET {{ _.base_url }}/users/1
드롭다운에서 활성 환경을 전환하면 변수를 사용하는 모든 요청이 업데이트됩니다. Insomnia는 또한 템플릿 태그를 지원합니다. 이는 타임스탬프, UUID를 생성하거나 이전 응답에서 값을 가져오기 위해 필드에 삽입할 수 있는 작은 함수입니다. 후자를 사용하면 요청을 연결할 수 있습니다. 예를 들어, 로그인 응답에서 토큰을 캡처하여 이후 요청에 사용할 수 있습니다.
응답 템플릿 태그는 Insomnia가 스크립팅 없이 요청 종속성을 처리하는 방식이므로 자세히 살펴볼 가치가 있습니다. "JSONPath $.token에 있는 로그인 요청의 본문을 사용하라"는 태그를 추가하고, 이를 모든 보호된 요청의 Authorization 헤더에 삽입합니다. 보호된 요청을 실행할 때 Insomnia는 필요한 경우 로그인 요청을 먼저 실행하고 토큰을 추출하여 대체합니다. 이 체인은 선언적으로 유지되므로 유지 관리할 글루 코드가 없습니다. 관련 검사를 그룹화하는 더 넓은 개념에 대해서는 API 테스트 케이스 예제 가이드를 참조하십시오.
어설션을 사용한 테스트 스위트 작성
요청을 보내면 응답이 표시됩니다. 응답이 올바른지 자동으로 확인하려면 Insomnia의 테스트 스위트 기능을 사용하며, 이는 컬렉션의 단위 테스트 탭으로 표시되기도 합니다.
컬렉션을 열고 테스트 뷰로 전환합니다. 테스트 스위트를 생성한 다음, 그 안에 개별 테스트를 추가합니다. 각 테스트는 작은 JavaScript 조각입니다. Insomnia는 Chai 어설션 라이브러리를 사용하며, 요청을 보내고 응답을 가져오는 헬퍼를 제공합니다. 테스트는 다음과 같습니다.
const response = await insomnia.send();
expect(response.status).to.equal(200);
본문을 파싱하고 필드를 확인함으로써 더 구체적으로 만들 수 있습니다.
const response = await insomnia.send();
const body = JSON.parse(response.data);
expect(response.status).to.equal(200);
expect(body.email).to.equal("daniel.okafor@example.com");
expect(body).to.have.property("id");
스위트의 각 테스트는 드롭다운에서 선택된 컬렉션의 요청을 대상으로 하므로, 테스트는 무엇을 보낼지 알 수 있습니다. 테스트 실행을 클릭하면 Insomnia는 스위트의 모든 테스트를 실행하고, 각 테스트의 통과 여부와 소요 시간을 보여줍니다. 이것이 회귀 검사입니다. 변경 후 스위트를 실행하면 API가 여전히 제대로 작동하는지 즉시 확인할 수 있습니다.
스위트 수가 늘어남에 따라 스위트를 구성하는 방식이 중요합니다. 일반적인 패턴은 리소스당 하나의 스위트를 사용하는 것입니다. 따라서 모든 아티클 테스트는 함께 있고 모든 사용자 테스트는 함께 있습니다. 스위트 내에서 각 테스트는 단일 동작에 집중해야 합니다. 해피 경로를 위한 하나의 테스트, 찾을 수 없는 경우와 유효성 검사 오류 경우를 위한 별도의 테스트를 만듭니다. 테스트가 실패하면, 어설션 코드를 읽을 필요 없이 해당 이름과 좁은 범위가 무엇이 문제인지 알려주어야 합니다. 좋은 검사를 작성하는 방법에 대한 더 깊은 내용은 API 어설션 가이드에서 무엇을 어설션하고 무엇을 건너뛰어야 하는지 설명하며, API 테스트 자동화를 위한 테스트 스위트 문서는 스위트가 성장함에 따라 구조화하는 방법을 다룹니다.
Inso를 사용하여 명령줄에서 실행
GUI는 개발에는 좋지만, 자동화에는 헤드리스(headless) 방식이 필요합니다. Insomnia는 Inso라는 명령줄 도우미를 제공합니다. 컬렉션을 내보내거나 동기화한 후 터미널에서 테스트 스위트를 실행합니다.
inso run test "User API tests"
Inso는 테스트 중 하나라도 실패하면 0이 아닌 상태 코드로 종료됩니다. 이는 CI 파이프라인에서 빌드를 실패로 표시하는 데 필요한 동작입니다. 이를 GitHub Actions 또는 다른 실행기에 연결하여 푸시할 때마다 Insomnia 테스트가 실행되도록 할 수 있으며, 깨진 엔드포인트가 팀원이나 프로덕션에 도달하기 전에 잡아낼 수 있습니다. Inso는 또한 API 사양을 린트하고 표준 형식으로 테스트 보고서를 생성할 수 있어 단순히 스위트 실행 이상의 용도로 유용합니다. CI/CD에서 API 테스트 자동화에 대한 문서는 Inso에 깔끔하게 적용되는 일반적인 패턴을 보여줍니다.
버전 8 클라우드 변경 및 대안
Insomnia 8은 클라우드 우선 모델로 전환했습니다. 기본적으로 사용자에게 Kong 계정을 만들고 프로젝트를 클라우드에 저장하도록 유도했습니다. 이전 버전이 완전히 로컬 기반이며 오프라인 친화적이었기 때문에 이 결정은 커뮤니티의 일부를 실망시켰습니다. 이후 릴리스에서는 더 명확한 로컬 전용 또는 "스크래치 패드" 옵션이 복원되었지만, 이 사건으로 인해 일부 팀은 특히 데이터가 외부로 유출될 수 없는 환경에서 대안을 찾게 되었습니다.
만약 그렇다면, Apidog를 살펴보는 것이 좋습니다. Apidog는 설계, 디버깅, 모의, 테스트 및 문서화를 포괄하는 올인원 API 플랫폼이며, Insomnia 내보내기를 가져올 수 있으므로 처음부터 다시 시작할 필요가 없습니다. Apidog는 JavaScript를 작성하지 않고도 시각적으로 어설션을 구축할 수 있게 하며, 필요할 때는 스크립트도 지원합니다. API 사양, 테스트 데이터 및 모의 서버가 하나의 프로젝트를 공유하므로, 테스트가 실제 계약과 일치하며 벗어나지 않습니다. Apidog를 다운로드하고 Insomnia 컬렉션을 가져와서 나란히 비교해 볼 수 있습니다. 더 넓은 범위의 조사를 위해서는 무료 온라인 API 테스트 도구 목록에서 여러 옵션을 다루고 있습니다.
Insomnia는 여전히 강력하고 집중적인 클라이언트이며, 특히 미니멀하고 방해 없는 인터페이스와 빠른 시작을 중요하게 여기는 개인 개발자와 소규모 팀에게 적합합니다. 올바른 선택은 팀의 작업 방식과 API 라이프사이클의 어느 부분을 여러 도구에 분산시키지 않고 한 곳에서 처리하고 싶은지에 달려 있습니다.
자주 묻는 질문
Insomnia는 무료로 사용할 수 있나요?
Insomnia는 요청 전송 및 로컬에서 테스트 스위트 실행을 포함하여 개인 사용을 위한 무료 티어를 제공합니다. 유료 요금제는 팀 협업 및 더 큰 클라우드 동기화 제한을 추가합니다. 비용을 지불하지 않고도 핵심 클라이언트를 사용할 수 있으며, 최근 버전에서는 클라우드 동기화를 사용하지 않으려는 경우 완전히 로컬에서 작업할 수 있습니다.
Insomnia는 어떤 프로토콜을 지원하나요?
Insomnia는 HTTP, REST, GraphQL, gRPC, SOAP 및 WebSocket을 처리합니다. 요청 설정은 프로토콜마다 다르지만, 응답 검사 및 HTTP 기반 요청의 경우 테스트 스위트 어설션은 모든 프로토콜에서 일관되게 작동합니다.
Insomnia에서 어설션을 어떻게 작성하나요?
테스트 스위트 기능을 사용하십시오. 컬렉션에서 테스트 뷰를 열고 스위트를 생성한 다음 테스트를 추가합니다. 각 테스트는 insomnia.send()를 호출하여 요청을 실행한 다음, 상태, 헤더 또는 파싱된 본문에 대해 Chai 스타일의 expect 어설션을 사용하는 JavaScript입니다. 테스트 실행 버튼으로 전체 스위트를 실행하십시오.
Insomnia 8에서 무엇이 변경되었나요?
Insomnia 8은 클라우드 우선 기본 설정으로 전환되어 사용자에게 Kong 계정에 로그인하고 프로젝트를 클라우드에 동기화하도록 유도했습니다. 일부 사용자는 의무적인 계정 흐름과 순수 로컬 앱에서 벗어나는 것에 불만을 가졌습니다. 이후 업데이트에서 더 명확한 로컬 전용 옵션이 추가되었지만, 이러한 변화로 인해 일부 팀은 대안을 평가하게 되었습니다.
CI 파이프라인에서 Insomnia 테스트를 실행할 수 있나요?
네, 가능합니다. 명령줄 도우미인 Inso를 사용하세요. 컬렉션을 내보내거나 동기화한 다음, 파이프라인에서 inso run test "<suite name>"을 실행합니다. Inso는 실패 시 0이 아닌 종료 코드를 반환하므로, API 테스트가 실패하면 CI가 자동으로 빌드를 실패 처리할 수 있습니다.