inso, 즉 Kong의 Insomnia CLI에서 API 테스트를 실행하고 변화를 고려 중이시라면, 이 가이드는 처음부터 끝까지 그 과정을 안내합니다. Insomnia에서 스펙과 테스트 스위트를 내보내고, 이를 Apidog으로 가져와서, inso run 명령을 apidog run 명령으로 다시 작성하는 방법을 보게 될 것입니다. 기존 CI 스크립트를 한 줄씩 매핑할 수 있도록 전/후 명령 테이블도 제공됩니다.
팀이 inso에서 Apidog CLI로 마이그레이션하는 이유
inso는 훌륭한 도구입니다. 요청 실행, Spectral 린팅, 단위 테스트를 터미널로 가져오며, Insomnia의 Git 동기화로 생성된 .insomnia 디렉토리에서 읽어옵니다. 이 워크플로가 당신에게 적합하다면, 떠나야 할 이유는 없습니다.
보통 문제는 CLI가 아니라 Insomnia 앱에서 시작됩니다. 다음 두 가지가 대부분의 마이그레이션 검색을 유도합니다.
- 필수 클라우드 계정. 2023년에 출시된 Insomnia 8은 많은 팀을 당황하게 한 필수 로그인/클라우드 계정을 도입했습니다. 많은 개발자들이 로컬 우선 클라이언트를 원했지만, 대신 로그인 장벽에 부딪혔습니다.
- 데이터 손실 및 마이그레이션 문제. 일부 사용자는 해당 전환 과정에서 데이터 손실 및 마이그레이션 사고를 겪었습니다. 만약 그러한 경험이 있다면, 이미 그 비용을 알고 있을 것입니다. 지금 그러한 문제에서 복구 중이라면, 다음 가이드가 도움이 됩니다: Insomnia 데이터 복구 및 내보내기와 더 심층적인 Insomnia 8 데이터 손실 복구 및 마이그레이션 가이드.
다른 이유는 통합입니다. inso의 경우 CLI는 스택의 한 부분입니다: 요청을 위한 Insomnia, 린팅을 위한 Spectral, 모의(mock) 및 문서를 위한 별도의 도구. Apidog은 설계, 디버그, 테스트, 모의, 문서화를 하나의 플랫폼으로 통합하며, CLI는 해당 플랫폼의 테스트 측면을 실행합니다. 움직이는 부분이 적고, 단일 정보원(source of truth)을 가집니다.
커밋하기 전에 더 넓은 맥락을 원한다면, Apidog vs Insomnia와 Insomnia와 Apidog 중 적합한 API 개발 도구 선택하기에서 CLI가 아닌 전체 앱에 대한 장단점을 설명합니다.
시작하기 전에: 무엇이 이전되고 무엇이 이전되지 않는가
마이그레이션 중간에 예상치 못한 일이 발생하지 않도록 미리 기대치를 설정하십시오.
| Insomnia의 자산 | Apidog으로 이전됩니까? | 방법 |
|---|---|---|
| OpenAPI / 설계 문서 | 예 | YAML/JSON으로 내보내고 Apidog으로 가져오기 |
| 요청 컬렉션 | 예 | 내보낸 다음 가져오기 |
| 환경 및 변수 | 예 | Apidog 환경으로 재구성 |
단위 테스트 스위트 (inso run test) |
부분적으로 | Apidog 테스트 시나리오로 재구성 |
Spectral 린트 구성 (inso lint spec) |
1:1 아님 | 아래 솔직한 참고 사항 참조 |
솔직한 참고 사항: inso lint spec은 Stoplight의 OpenAPI 린터인 Spectral을 실행하며, 이는 진정한 강점입니다. Apidog CLI는 독립 실행형 스펙 린터, 스타일 가이드, 분할, 병합 또는 번들 명령을 제공하지 않습니다. Apidog은 가져올 때 스펙을 검증하므로 구조적 문제는 가져오는 시점에 나타나지만, 파이프라인이 사용자 지정 Spectral 규칙 세트에 의존하는 경우 Apidog과 함께 Spectral을 CI에 유지하십시오. apidog lint를 기대하지 마십시오. 그런 기능은 없으며, 그렇게 가장하면 나중에만 문제가 발생할 것입니다.
단계 1: Insomnia에서 스펙 및 테스트 내보내기
inso는 설계 문서를 파일에 직접 작성할 수 있습니다. 스펙은 Insomnia 앱에서 보이는 이름과 동일한 이름으로 참조됩니다:
# OpenAPI 설계 문서를 YAML 파일로 내보내기
inso export spec "My API Design" --output my-api.yaml
inso가 데이터를 찾을 수 없는 경우, 올바른 소스를 지정하십시오. 기본적으로 작업 디렉토리 또는 Insomnia 앱 데이터 디렉토리의 .insomnia 디렉토리에서 읽습니다. --workingDir 또는 --src로 재정의하십시오:
inso export spec "My API Design" --workingDir ./design --output my-api.yaml
요청 컬렉션 및 inso가 깔끔하게 내보내지 않는 모든 항목의 경우, Insomnia 앱 자체를 사용하십시오: 앱을 열고 워크스페이스를 선택한 다음 내보내기(Export)를 사용하여 OpenAPI 또는 Insomnia v4 파일을 생성하십시오. 설계 문서와 컬렉션 내보내기를 모두 보관하십시오. 별도로 가져올 것입니다.
복구 중이고 앱이 제대로 작동하지 않는 경우, 내보내기 및 복구 가이드에서 Git 동기화 또는 클라우드 계정이 문제를 일으킬 때 데이터를 가져오는 방법을 설명합니다.
단계 2: Apidog으로 가져오기
Apidog을 열고 프로젝트를 생성한 다음 방금 내보낸 YAML 또는 JSON을 가져오십시오. Apidog은 OpenAPI를 기본적으로 읽으므로, 엔드포인트, 스키마, 예시 데이터가 편집, 모의(mock), 테스트할 수 있는 구조화된 리소스로 저장됩니다.
또한 자동화된 설정의 일부로 CLI에서 가져올 수도 있습니다. 이는 UI를 클릭하는 대신 팀 전체 이동을 스크립팅할 때 유용합니다. Apidog은 터미널에서 로그인 또는 액세스 토큰을 통해 인증하여 OpenAPI를 가져오고 엔드포인트, 스키마, 환경, 브랜치, 병합 요청을 코드로 관리합니다. CLI를 처음 설정하는 경우, Apidog CLI 설치 가이드 및 완벽한 CLI 가이드에서 설정 및 인증 흐름을 다룹니다.
가져올 때 Apidog은 스펙을 검증합니다. OpenAPI에 구조적 문제가 있는 경우, 런타임이 아닌 지금 알게 될 것입니다. 이는 inso lint spec과 가장 유사하지만, 반복할 가치가 있는 한 가지 차이점이 있습니다: 구성 가능한 Spectral 규칙 세트가 아닌 유효성 검사입니다.
단계 3: 명령 매핑하기 (기다리던 부분)
이것이 마이그레이션의 핵심입니다. inso 명령이 apidog run으로 어떻게 변환되는지는 다음과 같습니다.
| 원하는 작업 | inso 명령 | Apidog CLI와 동등한 명령 |
|---|---|---|
| 단위 테스트 스위트 실행 | inso run test "Smoke Suite" --env "Staging" |
apidog run --test-scenario "Smoke Suite" -e staging |
| 컬렉션 실행 | inso run collection "Checkout Flow" --env "Staging" |
apidog run "Checkout Flow" -e staging |
| 명명된 스크립트 실행 | inso script ci-smoke --env <env-id> |
apidog run -e <env-id> (CI 스크립트에 연결됨) |
| OpenAPI 스펙 린트 | inso lint spec "My API Design" |
1:1 매핑 없음; Apidog은 가져올 때 검증 |
| 스펙을 파일로 내보내기 | inso export spec "My API Design" --output api.yaml |
런타임 단계가 아닌 Apidog 가져오기/내보내기로 처리됨 |
매핑에 대한 몇 가지 참고 사항:
- 환경.
inso는--env "name"을 사용합니다. Apidog은-e(--env)를 사용합니다. 둘 다 어떤 환경의 기본 URL과 변수를 적용할지 선택합니다. 먼저 Insomnia 환경을 Apidog 환경으로 재구성한 다음, 이름 또는 ID로 참조하십시오. - 테스트 스위트는 테스트 시나리오가 됩니다.
inso run test가 Insomnia 단위 테스트 스위트를 실행하는 반면, Apidog은 테스트 시나리오를 실행합니다. 개념은 명확하게 매핑됩니다: 어설션이 포함된 순서 있는 요청. Apidog에서 스위트를 한 번 재구성하면, 모든apidog run에서 실행됩니다. inso script는 간접화였습니다. 명명된 스크립트 뒤에 명령을 래핑했다면, CI 단계에서apidog run을 직접 호출하거나 자신만의 npm/make 스크립트로 래핑하십시오.
명령별 심층 비교를 위해 Apidog CLI vs inso (Insomnia CLI)는 플래그별로 다룹니다. 과거에 Newman 또는 Postman CLI를 사용했다면, Apidog CLI vs Newman 및 Apidog CLI vs Postman CLI도 다룹니다.
단계 4: 리포터 이동
inso는 CI를 위한 테스트 출력과 JUnit 스타일 보고에 의존합니다. Apidog은 CLI, HTML, JSON 형식의 리포터를 제공하므로 빌드에서 사람이 읽을 수 있는 결과를 콘솔에 출력하고 동시에 기계가 읽을 수 있는 아티팩트를 생성할 수 있습니다:
# 시나리오를 실행하고 CLI 요약 및 HTML 보고서를 모두 출력
apidog run --test-scenario "Smoke Suite" -e staging -r cli,html
다운스트림 도구가 결과를 파싱해야 할 때는 json을, 사람이 빌드를 검토할 때는 html을, 실시간 콘솔 피드에는 cli를 선택하십시오. 또한 --upload-report를 사용하여 결과를 Apidog의 클라우드 테스트 보고서에 푸시하여 전체 팀이 CI 로그를 뒤질 필요 없이 실행 결과를 볼 수 있도록 할 수 있습니다. 테스트 보고서 가이드에서 형식을 자세히 다룹니다.
단계 5: 데이터 기반 테스트 가져오기
Insomnia 스위트가 데이터를 순회했다면, Apidog은 데이터 기반 테스트를 기본적으로 지원합니다. -d로 CSV 또는 JSON 데이터세트를 제공하면 시나리오가 각 행당 한 번 실행됩니다:
apidog run --test-scenario "Login Matrix" -e staging -d ./users.csv -r cli,json
이것은 Apidog이 inso를 통해 외부 데이터를 연결하는 것보다 덜 덧붙여진 느낌을 주는 부분 중 하나입니다. 데이터 기반 테스트 가이드에서 데이터세트 형식과 변수 바인딩에 대해 설명합니다.
단계 6: CI에 연결
마지막 단계는 파이프라인에서 명령을 교체하는 것입니다. 이전 GitHub Actions 또는 GitLab 단계는 아마 다음과 같았을 것입니다:
# 이전: CI의 inso
inso run test "Smoke Suite" --env "CI" --reporter junit
Apidog과 동등한 명령:
# 이후: CI의 Apidog CLI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json --upload-report
CI 시크릿으로 저장된 액세스 토큰으로 러너를 인증하십시오. 이는 다른 자격 증명이 필요한 단계를 처리하는 방식과 동일합니다. CI/CD 파이프라인 가이드와 GitHub Actions 가이드에는 복사-붙여넣기 워크플로 파일이 있습니다. 토큰 및 로그인 세부 정보는 Apidog CLI 인증을 참조하십시오.
린팅을 위해 Spectral을 유지했다면(사용자 지정 규칙이 있는 경우 권장), 이제 파이프라인에는 두 개의 게이트가 있습니다: Spectral이 스펙을 린트하고, Apidog이 테스트를 실행합니다. 이는 완벽하게 합리적인 최종 상태이며, 각 도구가 가장 잘하는 것에 대해 솔직하게 접근하는 것입니다.
Spectral을 유지하기
이전되지 않는 한 가지에 대해 분명히 하자면: 린팅이 계약의 일부라면, 그것을 버리지 마십시오. Spectral은 오픈 소스이며 Insomnia 외부에서도 잘 실행됩니다. 일반적인 하이브리드 CI는 다음과 같습니다:
# Spectral로 린트 (inso 설정에서 유지)
npx @stoplight/spectral-cli lint my-api.yaml
# Apidog CLI로 테스트
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json
린팅 측면에서는 아무것도 잃지 않고, 다른 모든 것에 대해서는 Apidog의 통합된 설계-모의-테스트-문서 플랫폼을 얻습니다. 이것이 정확한 거래이며, 대부분의 팀에게 좋은 거래입니다.
inso vs Apidog CLI 한눈에 보기
| 기능 | inso (Insomnia CLI) | Apidog CLI |
|---|---|---|
| 컬렉션 / 스위트 실행 | 예 | 예 |
| 환경 | --env |
-e / --env |
| OpenAPI 린팅 | 예 (Spectral) | 독립 실행형 명령 없음 (가져올 때 검증) |
| 데이터 기반 테스트 | 제한적 | 예 (-d, CSV/JSON) |
| 보고서 형식 | CLI, JUnit | CLI, HTML, JSON, 클라우드 업로드 |
| 코드로 리소스 관리 | .insomnia 디렉토리 읽기 |
엔드포인트, 스키마, 브랜치, 병합 요청 |
| 통합 플랫폼의 일부 | Insomnia + 외부 도구 | 하나의 플랫폼 (설계, 모의, 문서, 테스트) |
| 앱에 클라우드 계정 필요 | 예 (Insomnia 8+) | Apidog 계정, 로컬 친화적 |
자주 묻는 질문
Insomnia OpenAPI 스펙이 수정 없이 Apidog으로 가져와집니까? 보통 그렇습니다. Apidog은 OpenAPI를 기본적으로 읽고 가져올 때 검증합니다. 검증에서 문제가 발생하면, 일반적으로 스펙의 실제 구조적 문제이며, 한 번 수정하면 다운스트림의 모든 도구에 이점을 제공합니다.
Apidog CLI에 inso lint spec과 같은 lint 명령이 있습니까? 아니요. Apidog은 가져올 때 스펙을 검증하지만, 독립 실행형 CLI 린터 또는 스타일 가이드 명령은 없습니다. 사용자 지정 Spectral 규칙 세트에 의존하는 경우, apidog run 옆에 Spectral을 파이프라인에 유지하십시오. Redocly CLI에는 린터가 포함되어 있으므로, 나란히 비교하려면 Apidog CLI vs Redocly CLI를 참조하십시오.
inso를 실행했던 것과 같은 방식으로 CI에서 Apidog CLI를 실행할 수 있습니까? 예. 명령을 교체하고, CI 시크릿에서 액세스 토큰으로 인증한 다음, 리포터를 선택하십시오. CI/CD 가이드에는 완전한 워크플로 예시가 있습니다.
Insomnia 단위 테스트 스위트는 어떻게 됩니까? Apidog 테스트 시나리오로 재구성해야 합니다. 구조는 직접적으로 이어집니다: 순서 있는 요청과 어설션. 한 번만 재구성하면, 그 후에는 모든 apidog run에서 실행됩니다.
데이터 손실 사고 때문에 Insomnia에서 마이그레이션 중입니다. 어디서부터 시작해야 합니까? 먼저 복구 및 내보내기 가이드를 사용하여 데이터를 복구한 다음, 위 단계 2에 따라 정리된 내보내기 파일을 Apidog으로 가져오십시오.
마무리
inso에서 Apidog CLI로 마이그레이션하는 것은 대부분 번역 작업입니다: 스펙과 스위트를 내보내고, Apidog으로 가져오고, inso run test와 inso run collection을 apidog run으로 다시 작성하고, --env를 -e로 전환하고, 리포터를 Apidog의 CLI/HTML/JSON 출력으로 지정하십시오. 린팅을 한다면 Spectral을 유지하십시오. Apidog은 가져올 때 검증하지만 사용자 지정 규칙 세트를 대체하지는 않습니다.
그 결과는 계속해서 엮어야 하는 스택 대신 하나의 플랫폼을 얻는 것입니다. 시도할 준비가 되셨습니까? Apidog을 다운로드하고 방금 내보낸 스펙에 대해 첫 번째 apidog run을 실행하십시오.