Hoppscotch CLI란?

Hoppscotch는 오픈 소스 API 생태계로, 웹 앱, 데스크톱 앱, CLI, 그리고 자체 호스팅 가능한 백엔드를 포함하며, 종종 Postman 및 Insomnia의 오픈 소스 대안으로 설명됩니다. Hoppscotch CLI는 이 생태계에서 구축한 컬렉션을 터미널에서 실행하는 구성 요소이며, 이는 CI/CD에 정확히 필요한 기능입니다.

이 가이드에서는 Hoppscotch CLI가 무엇인지, 설치 방법, 그리고 실제 플래그와 작동하는 CI 예시를 통해 hopp test 명령이 실제로 어떻게 작동하는지 설명합니다. 다른 러너들과 비교하고 있다면, 최고의 Hoppscotch CLI 대안 게시물에서 여러 옵션을 비교하고, Apidog CLI vs Hoppscotch CLI는 직접적인 일대일 비교를 제공합니다.

버튼

Hoppscotch CLI란 무엇인가요?

Hoppscotch CLI는 npm 패키지 @hoppscotch/cli로 제공됩니다. 이 도구의 역할은 명확하고 유용합니다: Hoppscotch 컬렉션을 가져와서 그 안에 있는 모든 요청을 실행하고, 해당 요청에 연결된 테스트 스크립트를 실행하며, 파이프라인에서 읽을 수 있는 통과/실패 코드를 반환하며 종료하는 것입니다.

이는 Postman의 Newman이나 Insomnia의 inso와 같은 컬렉션 러너로 만듭니다. API를 설계하거나, 엔드포인트를 모의하거나, 문서를 생성하지 않습니다. 요청을 실행하고 어설션을 확인합니다. 자체 호스팅도 가능한 무료 오픈 소스 도구의 경우, 이러한 초점이 핵심입니다.

Hoppscotch는 오픈 소스이므로 전체 스택을 직접 실행하고 CLI를 자체 인스턴스에 연결할 수 있습니다. 요청 데이터가 공급업체 클라우드에 있는 것을 원치 않는 팀들은 이러한 점을 선호하는 경향이 있습니다. 단점은 호스팅을 직접 관리해야 한다는 것입니다.

Hoppscotch CLI 설치하기

npm을 통해 전역으로 설치합니다:

npm i -g @hoppscotch/cli

주의해야 할 한 가지 요구 사항: 현재 CLI는 Node.js v22 이상이 필요합니다. Node 20을 사용 중이라면 CLI v0.26.0에 머무를 수 있지만, 최신 릴리스는 v22 이상을 가정합니다. 빌드 에이전트에 연결하기 전에 버전을 확인하세요:

node --version
hopp --version

CI 이미지에 이전 버전의 Node가 포함되어 있다면, 파이프라인에서 런타임을 v22로 고정하세요. 그렇지 않으면 테스트와 관련 없어 보이는 설치 또는 런타임 오류가 발생할 수 있습니다.

hopp test 명령

모든 것은 hopp test를 통해 실행됩니다. 기본 형태는 컬렉션 파일을 가리킵니다:

hopp test ./my-collection.json

환경 파일과 요청 간 지연 시간을 전달할 수 있습니다:

hopp test ./my-collection.json -e ./staging.env.json -d 500

여기서 -e (또는 --env)는 환경을 제공하고, -d (또는 --delay)는 요청 사이에 지정된 밀리초만큼 기다립니다. 이는 속도 제한이 있는 API를 호출할 때 유용합니다.

컬렉션이 로컬 파일이 아닌 Hoppscotch 인스턴스(클라우드 또는 자체 호스팅)에 있는 경우, ID로 참조하고 개인 액세스 토큰으로 인증합니다:

hopp test <collection-id> --token <access_token> --server https://hoppscotch.your-company.com

--token은 개인 액세스 토큰을 전달하고, --server는 자체 호스팅 URL을 가리킵니다. 호스팅된 Hoppscotch 클라우드를 사용하는 경우 --server를 생략합니다.

데이터 기반 실행 및 보고

두 가지 플래그를 사용하면 hopp test를 단일 통과 방식에서 CI 친화적인 방식으로 전환할 수 있습니다.

데이터 기반 테스트를 위해 CSV를 제공하고 실행할 반복 횟수를 설정합니다:

hopp test ./my-collection.json --iteration-data ./users.csv --iteration-count 3

--iteration-data는 각 실행에서 컬럼이 변수가 되는 CSV를 사용하며, --iteration-count는 컬렉션이 반복되는 횟수를 제어합니다. 이는 Newman의 -d와 동일한 개념이며, "50개 계정에 대해 로그인 흐름 실행"과 같은 일반적인 경우를 다룹니다.

보고를 위해 CLI는 JUnit XML을 작성하며, 대부분의 CI 시스템은 이를 수집하여 테스트 결과를 기본적으로 표시할 수 있습니다:

hopp test ./my-collection.json --reporter-junit ./report.xml

JUnit은 CLI가 생성하는 유일한 구조화된 보고서 형식입니다. HTML 아티팩트 또는 호스팅된 링크 가능한 보고서가 필요한 경우, 이 점을 미리 알아두는 것이 중요합니다. Apidog CLI와 같은 도구는 비교를 위해 CLI, HTML, JSON 보고서를 출력합니다.

실행 중 실제로 무엇이 실행되나요?

hopp test를 실행하면 CLI는 컬렉션을 순서대로 탐색하며, 각 요청에 대해 다음을 수행합니다:

사전 요청 스크립트를 실행합니다.
요청을 보냅니다.
테스트 스크립트를 실행하고 각 어설션을 평가합니다.

테스트 스크립트는 Hoppscotch의 스크립팅 API를 사용합니다: pw.test()는 테스트 블록을 정의하고 pw.expect()는 그 안에서 어설션을 수행합니다. 요청에 첨부된 작은 예시는 다음과 같습니다:

pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});

어떤 어설션이라도 실패하면 명령은 0이 아닌 코드로 종료됩니다. 모든 것이 통과하면 0으로 종료됩니다. 이러한 종료 코드 동작은 CI와의 전체 계약입니다: 0이 아닌 종료는 빌드를 실패시키며, 이는 정확히 원하는 바입니다.

GitHub Actions 예시

hopp test를 CI에 통합하는 것은 간단합니다. 이 워크플로는 Node 22 러너에 CLI를 설치하고 푸시할 때마다 컬렉션을 실행합니다:

name: API tests
on: [push]
jobs:
  hopp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm i -g @hoppscotch/cli
      - run: hopp test ./collection.json -e ./ci.env.json --reporter-junit ./report.xml

v22를 고정하는 setup-node 단계는 사람들이 종종 잊어버리는 부분입니다. 이 단계가 없으면 기본 러너 Node가 현재 CLI에는 너무 오래된 버전일 수 있습니다.

고려해야 할 제한 사항

Hoppscotch CLI는 제 역할을 훌륭히 수행하며, 그 범위에 대해 솔직합니다:

플랫폼이 아닌 컬렉션 러너입니다. 설계, 모킹 또는 문서화 기능은 없습니다. 해당 기능들은 다른 곳에서 가져와야 합니다.
컬렉션을 직접 내보내거나 호스팅합니다. CLI는 컬렉션 파일을 실행하거나, 사용자가 가리키는 인스턴스에서 컬렉션을 가져옵니다.
JUnit이 유일한 구조화된 보고서입니다. 내장된 HTML 또는 호스팅된 보고서는 없습니다.
Node v22 이상. 현재 릴리스의 필수 요구 사항입니다.

이러한 점들은 단점이 아니라, 작고 무료인 오픈 소스 도구의 한계입니다. "CI에서 컬렉션 실행"을 넘어 설계, 모킹, 풍부한 보고서를 포함한 데이터 기반 실행, 그리고 API 리소스를 코드로 관리하는 방향으로 요구 사항이 확장된다면 통합 플랫폼이 필요합니다. Apidog는 전체 API 라이프사이클을 다루며, Apidog CLI 완벽 가이드는 터미널 측면을 보여줍니다. Apidog를 다운로드하여 Hoppscotch 컬렉션을 직접 가져와 비교하거나, 마이그레이션 가이드를 읽을 수 있습니다.

자주 묻는 질문 (FAQ)

Hoppscotch CLI는 무료인가요? 네, 무료입니다. Hoppscotch 프로젝트 아래의 오픈 소스이며, 전체 생태계를 자체 호스팅할 수 있습니다. 공식 CLI 문서와 GitHub 저장소를 참조하세요.

hopp test와 Newman의 차이점은 무엇인가요? 둘 다 데이터 기반 반복 기능을 가진 컬렉션 러너입니다. Newman은 Postman 컬렉션을 실행하고, hopp test는 Hoppscotch 컬렉션을 실행합니다. CSV 반복 데이터 및 종료 코드 기반 통과/실패를 포함하여 개념적으로 매우 유사합니다.

Hoppscotch CLI가 자체 호스팅 서버의 컬렉션을 실행할 수 있나요? 네. hopp test <collection-id> --token <access_token> --server <your-url> 명령을 사용하여 자체 인스턴스에서 컬렉션을 가져와 실행할 수 있습니다.

HTML 보고서를 생성하나요? 직접적으로는 아닙니다. --reporter-junit를 통해 JUnit XML을 작성합니다. CLI, HTML, JSON 보고서를 함께 보려면 Apidog CLI 테스트 보고서와 비교해 보세요.

Hoppscotch CLI는 특히 Hoppscotch를 이미 사용하거나 자체 호스팅하는 경우 CI에서 API 컬렉션을 실행하는 깔끔하고 무료인 방법입니다. 그 범위, Node v22 고정, JUnit 출력 활용법을 알면 하나의 작업을 훌륭하게 수행합니다.

버튼