Insomnia API 클라이언트를 사용해 보셨다면, 요청을 보내고, OpenAPI 사양을 설계하며, 테스트를 작성할 수 있는 그래픽 환경을 가지고 계실 것입니다. 하지만 그래픽 도구는 여러분의 머신에서만 작동합니다. 동일한 테스트를 CI 파이프라인 내에서 실행하거나, 모든 풀 리퀘스트에서 사양을 린트하고 싶을 때, 터미널에서 작동하는 무언가가 필요합니다. 그 무언가가 바로 inso입니다.
이 가이드는 inso가 무엇인지, 어떻게 설치하는지, 매일 사용하게 될 정확한 명령들, 사양과 컬렉션을 찾는 방법, 그리고 그 한계가 어디에서 나타나는지를 설명합니다. 이 가이드를 마치면 inso CLI가 여러분의 워크플로우에 적합한지, 그리고 적합하지 않다면 무엇을 찾아야 할지 알게 될 것입니다.
inso란 무엇인가요?
inso는 현재 Kong이 유지보수하는 오픈 소스 API 클라이언트인 Insomnia의 명령줄 동반자입니다. Insomnia가 UI에서 수행하는 세 가지 작업을 스크립트 가능하게 만듭니다: 테스트 실행, 요청 컬렉션 실행, API 사양 린팅. 이는 데스크톱의 Insomnia와 CI/CD에서 원하는 자동화된 검사 사이의 다리 역할을 합니다.
"inso란 무엇인가요?"에 대한 짧은 답변: Insomnia를 열지 않고도 Insomnia 작업을 실행하는 방법입니다. 설계 문서나 컬렉션을 이름으로 지정하면, 앱이 이미 알고 있는 동일한 데이터에 대해 실행합니다.
inso CLI 설치하기
몇 가지 문서화된 경로가 있습니다. 여러분의 배포 방식에 맞는 것을 선택하세요.
Homebrew는 macOS와 Linux에서 가장 간단합니다:
brew install inso
Docker는 CI 러너를 위한 가장 깔끔한 선택입니다. 로컬 툴체인을 관리하고 싶지 않을 때 유용합니다:
docker pull kong/inso:latest
직접 다운로드할 수도 있습니다. Kong은 inso CLI 문서 사이트에 Windows, Linux, macOS용 zip 아카이브를 게시합니다. 이는 빌드 아티팩트에서 고정된 버전을 원할 때 편리합니다.
과거에는 inso가 npm을 통해 `insomnia-inso`로도 배포되었습니다. 이 경로는 여전히 존재하지만, 현재 문서화되고 권장되는 경로는 Homebrew, Docker 및 직접 다운로드입니다. 새로운 것을 설정하는 경우, 이들을 선호하세요.
설치가 완료되었는지 확인하세요:
inso --version
핵심 inso 명령
inso는 작고 집중된 표면을 가집니다. 다음은 여러분이 실제로 사용하게 될 명령과 실제 예시입니다.
inso run test
Insomnia에서 작성한 단위 테스트 스위트를 지정된 환경에 대해 실행합니다:
inso run test "Payments API tests" --env "Staging"
스위트와 환경 모두 Insomnia 데이터에 표시된 것과 정확히 동일한 이름으로 참조됩니다. `inso run test` 명령은 어떤 어설션이 실패하면 0이 아닌 값으로 종료되며, 이는 CI 게이트로 사용될 수 있게 합니다.
inso run collection
컬렉션의 모든 요청을 순서대로 실행하며, 역시 지정된 환경에 대해 실행합니다:
inso run collection "Checkout flow" --env "Staging"
이것은 UI에서 "전체 폴더 재생"과 가장 유사합니다. 모든 엔드포인트가 예상대로 응답하는지 확인하려는 스모크 테스트에 유용합니다.
inso lint spec
OpenAPI 설계 문서를 검증합니다:
inso lint spec "Orders API"
내부적으로, `inso lint spec`은 Stoplight의 오픈 소스 OpenAPI 및 JSON 린터인 Spectral을 사용합니다. 이것은 분명히 강조할 가치가 있는 진정한 강점입니다: 얕은 구문 검사가 아니라, 성숙한 규칙 세트를 가진 실제, 규칙 기반의 사양 린팅을 얻을 수 있습니다. 여러분의 팀이 사양에 대한 스타일 가이드 준수를 중요하게 생각한다면, 이 명령은 많은 사람들이 inso를 사용하는 이유가 됩니다.
inso export spec
설계 문서를 디스크의 파일로 내보냅니다:
inso export spec "Orders API" --output orders.yaml
사양을 다른 생성기에 공급하거나, 스냅샷을 커밋하거나, 일반 YAML 파일을 예상하는 도구에 전달하고 싶을 때 유용합니다.
inso script
Insomnia 데이터에 정의된 이름 있는 스크립트를 환경 ID를 전달하여 실행합니다:
inso script deploy-smoke --env env_9f2a
이는 여러분의 사용자 정의 단계를 연결하기 위한 비상 탈출구입니다.
inso가 사양과 컬렉션을 찾는 방법
이것은 사람들이 혼란스러워하는 부분이므로, 정확하게 설명할 가치가 있습니다. inso는 스스로 아무것도 저장하지 않습니다. 다음 두 곳 중 한 곳에서 읽습니다:
- 작업 디렉토리의 `.insomnia` 디렉토리. 이것은 Insomnia의 Git Sync가 생성하는 것이므로, API 프로젝트를 리포지토리에 커밋할 때, inso는 체크아웃에서 직접 읽을 수 있습니다. 이것이 CI에 필요한 패턴입니다.
- Insomnia 앱이 머신에 설치되어 있다면, Insomnia 애플리케이션 데이터 디렉토리에서 읽습니다. 이것은 로컬에서는 편리하지만, 앱이 설치된 적이 없는 깨끗한 CI 러너에서는 쓸모없습니다.
소스를 명시적으로 재정의할 수 있습니다:
inso lint spec "Orders API" --workingDir ./api-project
# 또는 정확한 소스를 지정
inso run test "Payments API tests" --src ./api-project/.insomnia
핵심적인 정신 모델: inso는 모든 것을 이름(또는 ID)으로 참조하며, 이 이름들은 찾은 데이터 소스에 대해 해석됩니다. `.insomnia` 디렉토리나 앱 데이터에 이름이 없으면 inso는 실행할 수 없습니다. inso를 독립된 OpenAPI 파일로 지정하고 "이것을 테스트하라"고 말하는 개념은 그 파일이 Insomnia 프로젝트 구조 내에 존재하지 않는 한 없습니다.
최소 CI 예시
다음은 리포지토리에 커밋된 Git 동기화된 `.insomnia` 디렉토리를 사용하여, 모든 푸시에 대해 사양을 린트하고 테스트 스위트를 실행하는 GitHub Actions 작업입니다:
name: API checks
on: [push]
jobs:
inso:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install inso
run: |
curl -sSL https://github.com/Kong/insomnia/releases/latest/download/inso-linux-x64.zip -o inso.zip
unzip inso.zip && sudo mv inso /usr/local/bin/
- name: Lint the spec
run: inso lint spec "Orders API" --workingDir .
- name: Run the test suite
run: inso run test "Payments API tests" --env "CI" --workingDir .
두 명령 모두 실패 시 0이 아닌 값으로 종료되므로, 깨진 사양이나 실패한 어설션은 작업을 실패하게 만듭니다. 이것이 이러한 검사를 GUI 밖으로 옮기는 전체적인 목적입니다.
솔직한 한계
inso는 자신이 하는 일을 잘 하지만, 분명한 한계가 있습니다.
Insomnia의 데이터 소스에 묶여 있습니다. 여러분의 사양, 컬렉션, 스위트는 Git Sync나 설치된 앱을 통해 나타나는 Insomnia 프로젝트 내에 존재해야 합니다. 만약 여러분의 팀이 Insomnia를 단일 진실 소스로 사용하지 않는다면, inso는 작동할 것이 없습니다.
모든 것은 이름으로 참조됩니다. 이는 읽기 쉽지만, 취약합니다. UI에서 스위트 이름을 변경하면, 이전 이름을 하드코딩한 CI 작업은 다음 실행까지 조용히 깨집니다. 이름은 또한 깔끔하게 해결될 만큼 충분히 고유해야 합니다.
범위는 의도적으로 좁습니다. inso는 테스트를 실행하고, 컬렉션을 실행하고, 사양을 린트하고, 내보내고, 스크립트를 실행합니다. 이것은 설계-목-문서-테스트 플랫폼이 아닙니다. 이 동사들을 넘어서는 모든 것에 대해서는 다시 GUI로 돌아가거나 다른 도구를 찾아야 합니다.
inso vs 통합된 대안
inso는 Insomnia가 이미 여러분의 클라이언트일 때 강력한 터미널 동반자입니다. 절충점은 여러분이 조각들을 엮는다는 것입니다: 설계 및 디버깅을 위한 Insomnia, CI를 위한 inso, 린팅을 위한 Spectral 규칙, 그리고 모의 및 문서를 위한 별도의 도구.
Apidog는 정반대의 입장을 취합니다. 설계, 모의, 문서화 및 테스트를 하나의 플랫폼에 통합하며, 그들의 Apidog CLI는 데이터 기반 테스트, 다양한 리포터 형식, 코드로서의 리소스 및 브랜치를 통해 동일한 단일 진실 소스에서 테스트 시나리오와 컬렉션을 실행합니다. 여기서 공정하게 말하자면: Apidog CLI는 inso가 Spectral과 함께 하는 것처럼 독립적인 사양 린터를 제공하지 않으므로, Spectral 스타일의 스타일 가이드 준수가 우선이라면 inso가 그 부분에서 진정한 강점이 있습니다. Apidog가 앞서 나가는 부분은 통합입니다. 여러분은 다섯 가지 도구를 함께 붙이지 않아도 됩니다.
두 가지를 직접 비교하고 싶다면, Apidog CLI vs inso (Insomnia CLI)를 참조하거나, inso (Insomnia CLI)란 무엇인가에서 더 깊은 배경을 읽어보세요. inso가 올바른 선택이 아니라고 결정했다면, 최고의 inso 대안 모음과 inso에서 Apidog CLI로 마이그레이션 가이드는 단계별로 이동 과정을 안내합니다. GUI 클라이언트 자체에 대한 더 넓은 맥락은 Apidog vs Insomnia 및 Insomnia를 사용하여 API를 테스트하는 방법이 좋은 시작점입니다.
inso 설정과 함께 통합된 접근 방식을 나란히 보고 싶다면, Apidog를 무료로 다운로드할 수 있습니다.