Hoppscotch CLI에서 Apidog CLI로 마이그레이션하는 방법

Hoppscotch CLI는 터미널이나 CI 파이프라인에서 API 컬렉션을 실행하는 깔끔하고 무료 방법입니다. `hopp test` 명령어는 컬렉션 파일을 읽고, 모든 요청을 실행하며, 사전 요청 및 테스트 스크립트를 실행하고, 어설션이 실패하면 0이 아닌 값으로 종료됩니다. 많은 팀에게는 그것으로 충분합니다.

하지만 러너는 API 작업의 한 부분일 뿐입니다. 어느 시점에는 별도의 디자인 도구, 목 서버, 문서 사이트 및 러너를 동시에 사용하게 되며, 이들 중 어느 것도 단일 진실 소스를 공유하지 않습니다. 이때 보통 팀들은 Hoppscotch CLI에서 Apidog CLI로 마이그레이션하는 방법을 찾기 시작합니다. Apidog는 디자인, 디버깅, 목업, 문서화 및 테스트를 하나의 플랫폼으로 통합하며, 해당 CLI는 CI에서 테스트 측면을 실행합니다. 러너는 이미 알고 있는 형태를 유지합니다. 변하는 것은 그 주변의 모든 것입니다.

버튼

언제 마이그레이션해야 하고 (하지 말아야 하는지)

먼저 자신에게 솔직해지세요. 유일한 요구 사항이 "CI에서 무료로 컬렉션을 실행하고 싶다면 셀프 호스팅"이라면, Hoppscotch CLI는 정말 좋은 도구입니다. 오픈 소스이며, 러너는 빠르고, `@hoppscotch/cli`는 일반 npm 패키지로 제공됩니다. 계속 사용하는 것을 부끄러워할 필요는 없습니다.

다음 중 하나가 어려워지기 시작할 때 마이그레이션하세요:

하나의 도구에서 API를 디자인하고, 다른 도구에서 목업하며, 세 번째 도구에서 문서를 작성하고, 이들을 동기화하는 것이 수동 작업일 때.
테스트 실행, 목 서버 및 게시된 문서가 단일 프로젝트 정의를 공유하기를 원할 때.
더 풍부한 보고서 (이해 관계자를 위한 HTML 보고서, 기계를 위한 JSON)와 클라우드 호스팅된 실행 기록이 필요할 때.
엔드포인트, 스키마, 환경 및 브랜치를 CLI가 단순히 실행하는 것이 아니라 관리할 수 있는 코드로 취급하고 싶을 때.

위 목록이 당신의 한 주와 같다면, 러너가 아니라 플랫폼이 마이그레이션해야 할 이유입니다. 깔끔하게 마이그레이션하는 방법은 다음과 같습니다.

1단계: Hoppscotch 컬렉션 및 환경 내보내기

Hoppscotch의 모든 것은 JSON이므로 내보내기가 간편합니다.

Hoppscotch 앱(웹 또는 데스크톱)에서 CI에서 실행하는 컬렉션을 엽니다. 컬렉션 메뉴를 사용하고 **내보내기**를 선택하면 `.json` 파일이 생성됩니다. `-e` 옵션으로 전달하는 환경에 대해서도 동일하게 수행하세요: 환경 패널을 열고 해당 파일을 자체 JSON 파일로 내보냅니다.

로컬 파일에 대해 CLI를 이미 실행하고 있다면, 이 파일들은 이미 디스크에 있습니다. 일반적인 Hoppscotch CI 단계는 다음과 같습니다.

npm i -g @hoppscotch/cli
hopp test ./collections/checkout-api.json -e ./environments/staging.json

두 파일 모두 보관하세요. `checkout-api.json`은 컬렉션이고, `staging.json`은 환경입니다. 이 두 가지가 마이그레이션할 전체 페이로드입니다.

Node 버전에 대한 참고 사항입니다. 현재 Hoppscotch CLI는 Node.js v22 이상이 필요합니다. Node 20에 고정된 팀은 CLI v0.26.0을 유지합니다. Apidog CLI는 Node 버전에 얽매이지 않으므로, 마이그레이션은 버전 제약을 없앨 수 있는 기회이기도 합니다.

2단계: 컬렉션을 Apidog로 가져오기

Apidog에서 프로젝트를 생성하거나(또는 기존 프로젝트를 열고), Hoppscotch에서 내보낸 파일을 가져옵니다. Apidog는 일반적인 컬렉션 형식과 OpenAPI를 읽을 수 있으므로 컬렉션을 바로 가져올 수 있습니다. API에 OpenAPI 스펙도 있다면 그것도 가져오세요. Apidog는 가져올 때 스펙을 검증하므로, 구조적인 문제는 실행 중에 조용히 실패하는 대신 즉시 드러납니다.

Hoppscotch 환경을 동일한 변수 이름으로 Apidog 환경에 매핑합니다. `staging.json`에 `base_url`과 `api_token`이 정의되어 있다면, 해당 키들을 일치하는 Apidog 환경에 다시 생성합니다. 이름을 동일하게 유지하면 테스트 스크립트와 요청 URL을 수정할 필요가 없습니다.

이때 플랫폼의 이점이 나타나기 시작합니다. 가져온 엔드포인트는 이제 디자인 아티팩트가 됩니다. 스키마를 첨부하고, 이를 기반으로 목 서버를 생성하며, 테스트에 사용하는 동일한 정의에서 문서를 게시할 수 있습니다. Apidog CLI 전체 가이드는 설정 후 모든 기능을 다루며, 설치 가이드는 러너 바이너리를 다룹니다.

3단계: `hopp test`를 `apidog run`에 매핑하기

개념 모델은 직접적으로 이어집니다. Hoppscotch가 컬렉션 파일을 실행하는 곳에서 Apidog는 프로젝트의 테스트 시나리오 또는 컬렉션을 실행합니다. 동일한 작업이지만 진실 소스는 다릅니다.

# Hoppscotch
hopp test ./collections/checkout-api.json -e ./environments/staging.json

# Apidog
apidog run --access-token $APIDOG_TOKEN -e "Staging"

두 명령어 모두 모든 요청을 순서대로 실행하고, 사전 요청 스크립트를 실행하며, 테스트 어설션을 실행하고, 실패하는 경우 0이 아닌 종료 코드를 반환합니다. 이 종료 코드 계약은 CI가 의존하는 부분이며, 이는 보존되므로 파이프라인의 통과/실패 로직은 변경되지 않습니다.

인증 방식은 유용한 방식으로 다릅니다. Hoppscotch는 클라우드 또는 셀프 호스팅 컬렉션에 대해 `--token`으로 개인 액세스 토큰을 전달합니다. Apidog는 로그인 또는 액세스 토큰으로 인증하며, 이를 통해 CLI가 단일 내보내기 파일 대신 프로젝트 내의 리소스에 접근할 수 있게 합니다. 이전에 토큰 처리로 어려움을 겪었다면, 인증 가이드에서 옵션을 설명합니다.

4단계: 데이터 기반 실행 변환

두 도구 모두 데이터 기반 테스트를 수행하므로, 입력 CSV를 반복하는 기능은 마이그레이션 후에도 유지됩니다.

Hoppscotch에서는 반복 데이터와 횟수를 전달합니다.

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --iteration-count 50 \
  --iteration-data ./data/orders.csv

Apidog에서 러너는 `-d`로 데이터셋을 받습니다. CSV와 JSON을 허용하므로, 가져온 후 동일한 `orders.csv`가 작동합니다.

apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -d ./data/orders.csv

CSV 헤더 행은 요청 및 어설션 내에서 참조하는 변수 이름이 되며, Hoppscotch가 사용하는 것과 동일한 패턴이므로 테스트 본문을 다시 작성할 필요가 없습니다. Apidog 방식이 처음이라면, 데이터 기반 테스트 가이드에서 열을 변수에 바인딩하고 반복마다 한 행씩 실행하는 방법을 보여줍니다.

5단계: 리포터 변환

보고 기능은 플랫폼이 앞서는 부분이며, 변환은 간단합니다.

Hoppscotch는 하나의 플래그로 JUnit XML 파일을 생성하며, 대부분의 CI 시스템은 테스트 패널을 위해 이를 파싱합니다.

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --reporter-junit ./reports/results.xml

Apidog는 여러 리포터 옵션을 제공합니다: 읽기 쉬운 CLI 요약, 이해 관계자에게 전달할 수 있는 HTML 보고서, 그리고 기계를 위한 JSON 보고서입니다. 또한 공유 가능한 실행 기록을 위해 결과를 클라우드에 푸시할 수도 있습니다.

# Human-readable HTML report
apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -r html \
  --upload-report

CI 대시보드가 특별히 JUnit XML을 기대한다면, Apidog는 JUnit 플래그 대신 CLI/HTML/JSON 리포터와 클라우드 보고서를 사용하므로 전환 시 해당 통합을 염두에 두세요. 대부분의 팀에게는 HTML 보고서와 업로드된 클라우드 기록이 아무도 열어보지 않는 원시 XML 파일보다 한 단계 발전된 것입니다. 테스트 보고서 가이드는 각 형식과 사용 시기를 설명합니다.

이전과 이후: 명령어 매핑

작업	Hoppscotch CLI	Apidog CLI
설치	`npm i -g @hoppscotch/cli`	설치 가이드에 따름
컬렉션 실행	`hopp test collection.json`	`apidog run`
환경 선택	`-e env.json`	`-e "Staging"`
인증 토큰	`--token <pat>`	로그인 / `--access-token`
자체 호스팅 / 클라우드 대상	`--server <url>`	프로젝트 + 액세스 토큰
데이터 기반 입력	`--iteration-data orders.csv`	`-d orders.csv`
반복 실행	`--iteration-count 50`	반복 데이터셋
요청 간 지연 추가	`-d <ms>`	시나리오별 설정
JUnit 보고서	`--reporter-junit results.xml`	`-r json` (또는 CLI / HTML)
클라우드 실행 기록	내장되어 있지 않음	`--upload-report`

해당 표의 `-d` 플래그에 주목하세요. Hoppscotch에서 `-d`는 밀리초 단위의 지연을 의미합니다. Apidog에서 `-d`는 데이터 기반 실행을 위한 데이터셋입니다. 글자는 같지만 기능은 다릅니다. 이는 Hoppscotch에서 Apidog로 전환할 때 사람들이 혼동하는 함정 중 하나입니다.

6단계: GitHub Actions에 연결하기

마지막 단계이며, 목표는 처음부터 끝까지 성공적인 빌드를 확보하는 것입니다. 먼저 기존 Hoppscotch 작업 옆에 Apidog 작업을 설정하고, 통과하는지 확인한 다음, 이전 단계를 삭제하세요. 맹목적으로 전환하지 마십시오.

name: API tests
on: [push, pull_request]

jobs:
  apidog-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API tests
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          apidog run \
            --access-token "$APIDOG_TOKEN" \
            -e "Staging" \
            -d ./data/orders.csv \
            -r html \
            --upload-report

액세스 토큰은 리포지토리 비밀로 저장하고, YAML 파일에는 절대 저장하지 마세요. CLI는 어설션이 실패하면 0이 아닌 종료 코드를 반환하므로, 테스트가 실패할 때 정확히 작업이 실패합니다. 이는 팀이 Hoppscotch에서 이미 신뢰하고 있는 동작입니다. GitHub Actions 가이드는 캐싱 및 매트릭스 실행을 다루고, 더 넓은 범위의 CI/CD 파이프라인 가이드는 GitLab, Jenkins 등을 다룹니다.

Apidog 작업이 몇 번의 실행에서 성공적으로 완료되면, Hoppscotch 단계와 npm 설치를 제거합니다. 마이그레이션이 완료되었고, 빌드는 한 번도 실패하지 않았습니다.

Hoppscotch에 대한 공정한 평가

이 모든 것이 Hoppscotch를 폄하하는 것은 아닙니다. Hoppscotch의 CLI 러너는 빠르고 무료이며, 프로젝트는 완전한 오픈 소스이고, 전체 스택을 셀프 호스팅할 수 있습니다. 만약 가벼운 러너 외에 다른 것이 필요 없다면, Hoppscotch는 그 자리를 충분히 지킵니다. 전환해야 하는 이유는 범위에 있습니다. 디자인, 목업, 문서화 및 테스트가 모두 하나의 정의를 공유해야 할 때, 독립형 러너는 이를 제공할 수 없지만 통합 플랫폼은 가능합니다. Apidog CLI vs Hoppscotch CLI에서 두 러너를 직접 비교하고, CLI가 아닌 앱을 고려 중이라면 Postman vs Hoppscotch 및 Hoppscotch 대안 개요에서 추가 정보를 얻을 수 있습니다.