DEV Community

Cover image for API 테스트를 위한 최고의 경량 CLI 도구
Rihpig
Rihpig

Posted on • Originally published at apidog.com

API 테스트를 위한 최고의 경량 CLI 도구

대부분의 API 테스트 도구는 단일 요청을 보내기 전에 창을 열고 로그인한 뒤 작업 공간을 선택하게 합니다. 하지만 터미널에서 요청을 작성하고 응답을 확인한 다음 바로 다음 작업으로 넘어가는 흐름에는 맞지 않습니다. 경량 CLI 도구는 도구 자체를 뒤로 물리고, HTTP 요청과 응답을 작업의 중심에 둡니다.

지금 Apidog를 사용해 보세요

여기서 “경량”은 단순히 기능이 적다는 뜻이 아닙니다. 설치 공간이 작고, 빠르게 시작하며, 첫 요청을 보내기 위한 설정이 거의 없고, jq나 grep으로 연결할 수 있는 터미널 중심 출력을 제공한다는 의미입니다. 호스팅형 GUI까지 포함한 비교가 필요하다면 최고의 무료 API 테스트 도구를 참고하세요.

이 글에서는 REST 및 HTTP API 테스트에 사용할 수 있는 경량 CLI 도구 8가지를 다룹니다. 단일 요청을 빠르게 보내는 도구부터 CI에서 전체 테스트 스위트를 실행하는 도구까지 순서대로 살펴봅니다. 각 도구에는 설치 명령, 바로 실행할 수 있는 예제, 적합한 사용 사례와 한계를 포함했습니다.

API 테스트 CLI를 “경량”으로 만드는 기준

터미널에서 실행된다고 해서 모두 가벼운 도구는 아닙니다. 다음 네 가지를 기준으로 선택하세요.

  • 작은 설치 공간: 단일 바이너리, pip/npm 설치 또는 npx 한 줄 실행으로 시작할 수 있어야 합니다.
  • 빠른 시작 시간: 별도 워밍업이나 데몬 없이 실행 직후 요청을 보낼 수 있어야 합니다.
  • 낮은 설정 비용: 계정, 로그인, 프로젝트 파일 없이 첫 요청을 실행할 수 있어야 합니다.
  • 터미널 친화적 출력: 사람이 읽기 쉽고 다른 명령으로 파이프할 수 있어야 하며, CI에서 사용할 수 있는 의미 있는 종료 코드를 제공해야 합니다.

처음 세 기준은 수동 API 탐색에 특히 중요합니다. 네 번째 기준은 CI 파이프라인에서 테스트를 통과/실패 게이트로 사용하려면 필수입니다. 수동 호출 도구를 더 비교하려면 REST API 테스트를 위한 curl 대안도 확인하세요.

curl: 대부분의 환경에 이미 있는 기준 도구

curl은 macOS, 대부분의 Linux 배포판, 최신 Windows 환경에 기본 포함되어 있습니다. 즉, 가장 가벼운 설치 방식은 설치하지 않는 것입니다.

먼저 버전을 확인하고, JSON 요청을 보낸 뒤 상태 코드만 출력해 보세요.

# 이미 머신에 있을 가능성이 높습니다
curl --version

# JSON을 POST하고 HTTP 상태 코드만 출력합니다
curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{"user":"acme","plan":"pro"}'
Enter fullscreen mode Exit fullscreen mode

적합한 경우

  • 빠른 일회성 요청
  • 셸 스크립트
  • 새 도구를 설치할 수 없는 서버 또는 컨테이너

한계

  • 헤더, 인증, 본문을 수동으로 구성해야 합니다.
  • JSON 응답을 보기 좋게 출력하려면 jq 같은 별도 도구가 필요합니다.
  • 응답 검증은 직접 구현해야 합니다.

예를 들어 응답 JSON을 확인하려면 다음처럼 연결합니다.

curl -s https://httpbin.org/get | jq '.headers'
Enter fullscreen mode Exit fullscreen mode

HTTPie: 사람이 읽기 쉬운 curl 문법

HTTPie는 curl과 같은 HTTP 요청을 보내지만, API를 수동으로 탐색할 때 더 읽기 쉬운 문법을 제공합니다. 헤더와 JSON 필드를 간단한 key=value 형태로 작성할 수 있으며, 출력도 기본적으로 포맷됩니다.

python -m pip install httpie
# 또는: brew install httpie

# age:=24는 숫자, name=acme는 문자열로 전송합니다
http POST httpbin.org/post name=acme age:=24 plan=pro
Enter fullscreen mode Exit fullscreen mode

인증 헤더도 명확하게 작성할 수 있습니다.

http GET https://api.example.com/me \
  Authorization:"Bearer $TOKEN"
Enter fullscreen mode Exit fullscreen mode

적합한 경우

  • API를 수동으로 탐색할 때
  • curl 플래그보다 읽기 쉬운 명령을 선호할 때
  • 포맷된 응답을 즉시 확인하고 싶을 때

한계

  • Python 런타임이 필요합니다.
  • 컴파일된 단일 바이너리보다 시작 시간이 느릴 수 있습니다.
  • 테스트 실행기가 아니라 HTTP 클라이언트이므로 검증 로직은 별도로 구성해야 합니다.

xh: HTTPie 문법을 단일 Rust 바이너리로 사용

xh는 HTTPie 스타일 문법을 Rust로 구현한 도구입니다. key=value 형태의 요청 작성 방식은 유지하면서 빠른 시작 시간과 단일 바이너리 배포를 제공합니다.

brew install xh
# 또는: cargo install xh --locked

xh POST httpbin.org/post name=acme age:=24 plan=pro
Enter fullscreen mode Exit fullscreen mode

필요하다면 실행할 요청을 curl 명령으로 변환할 수도 있습니다.

xh --curl POST httpbin.org/post name=acme age:=24
Enter fullscreen mode Exit fullscreen mode

적합한 경우

  • HTTPie 문법을 선호하지만 Python 런타임은 피하고 싶을 때
  • 빠르게 시작하는 단일 바이너리 HTTP 클라이언트가 필요할 때
  • HTTP/2 요청을 다뤄야 할 때

한계

  • 모든 HTTPie 기능과 플러그인 생태계를 제공하지는 않습니다.
  • HTTP 요청 클라이언트이므로 복잡한 검증 엔진 역할은 하지 않습니다.

Hurl: 일반 텍스트 파일로 작성하는 HTTP 테스트

Hurl은 단순히 요청을 보내는 것을 넘어 응답을 검증합니다. .hurl 파일에 요청과 검증 조건을 작성하고, CI에서 --test 옵션으로 실행할 수 있습니다.

brew install hurl
# 또는: cargo install --locked hurl

cat > login.hurl <<'EOF'
POST https://httpbin.org/post
{ "user": "acme", "plan": "pro" }

HTTP 200
[Asserts]
jsonpath "$.json.user" == "acme"
EOF

hurl --test login.hurl
Enter fullscreen mode Exit fullscreen mode

검증이 실패하면 Hurl은 0이 아닌 종료 코드를 반환합니다. 따라서 CI 단계에서 별도 래퍼 스크립트 없이 바로 실패 게이트로 사용할 수 있습니다.

# GitHub Actions 예시
- name: Run API smoke test
  run: hurl --test login.hurl
Enter fullscreen mode Exit fullscreen mode

적합한 경우

  • HTTP 스모크 테스트
  • 계약 테스트
  • Git에서 리뷰하기 쉬운 일반 텍스트 테스트
  • 종료 코드 기반의 간단한 CI 게이트

한계

  • HTTP 중심 도구입니다.
  • gRPC 실행이나 실제 부하 생성 용도에는 맞지 않습니다.
  • 복잡한 분기와 로직이 필요한 흐름은 여러 .hurl 파일 또는 별도 스크립트가 필요할 수 있습니다.

Step CI: YAML로 작성하는 다단계 API 워크플로우

Step CI는 하나의 YAML 파일로 API 워크플로우를 정의하고 실행합니다. REST, GraphQL, gRPC, tRPC, SOAP를 다룰 수 있으며 OpenAPI 스키마 검증도 지원합니다.

npm install -g stepci

# workflow.yml에 단계, 값 캡처, 검증을 정의합니다
stepci run workflow.yml
Enter fullscreen mode Exit fullscreen mode

다단계 흐름은 다음처럼 구성할 수 있습니다.

  1. 로그인 요청을 보냅니다.
  2. 응답에서 토큰을 캡처합니다.
  3. 다음 요청의 Authorization 헤더에 토큰을 사용합니다.
  4. 최종 응답 상태와 데이터를 검증합니다.

적합한 경우

  • 로그인 → 토큰 추출 → 보호된 API 호출 같은 다단계 흐름
  • 로컬과 CI에서 같은 테스트 정의를 실행해야 할 때
  • 여러 API 프로토콜을 하나의 워크플로우에서 다뤄야 할 때

한계

  • Node.js 런타임이 필요합니다.
  • Rust 또는 Go 기반 단일 바이너리보다 설치 및 시작 비용이 클 수 있습니다.
  • 파이프라인에 도입하기 전 저장소의 최근 유지보수 상태를 확인하는 것이 좋습니다.

테스트 도구를 전체 품질 전략에 배치하는 방법은 API 테스트 전략에서 확인할 수 있습니다.

k6: 터미널에서 실행하는 부하 및 성능 테스트

k6는 “응답이 올바른가?”보다 “예상 부하를 견딜 수 있는가?”를 확인하는 도구입니다. Go로 작성되었고, 테스트 시나리오는 JavaScript로 작성합니다.

brew install k6
# 또는 Docker 사용:
# docker run grafana/k6

cat > load.js <<'EOF'
import http from 'k6/http';
import { check } from 'k6';

export const options = {
  vus: 10,
  duration: '30s',
  thresholds: {
    http_req_duration: ['p(95)<500'],
  },
};

export default function () {
  const res = http.get('https://httpbin.org/get');

  check(res, {
    'status is 200': (r) => r.status === 200,
  });
}
EOF

k6 run load.js
Enter fullscreen mode Exit fullscreen mode

위 예제는 가상 사용자 10명이 30초 동안 요청을 보내고, 95% 요청이 500ms 미만에 완료되어야 한다고 정의합니다. 임계값이 하나라도 위반되면 k6는 코드 99로 종료합니다.

적합한 경우

  • CI에서 자동 실행하는 성능 검사
  • 응답 시간 임계값 검증
  • 별도 클러스터 없이 실행하는 기본 부하 테스트

한계

  • 단일 응답을 수동으로 살펴보는 용도의 도구가 아닙니다.
  • 기능 테스트보다 부하와 성능 검증에 적합합니다.
  • 의미 있는 시나리오를 작성하려면 k6 JavaScript API를 익혀야 합니다.

Newman: Postman 컬렉션을 CI에서 헤드리스 실행

Newman은 Postman 컬렉션을 명령줄에서 실행하는 도구입니다. 이미 Postman에서 요청과 테스트를 작성했다면, 컬렉션과 환경 파일을 내보내 CI에서 바로 실행할 수 있습니다.

npm install -g newman

# Postman에서 내보낸 컬렉션과 환경 파일을 실행합니다
newman run collection.json -e staging.json
Enter fullscreen mode Exit fullscreen mode

CI에서는 다음처럼 사용할 수 있습니다.

- name: Run Postman collection
  run: newman run collection.json -e staging.json
Enter fullscreen mode Exit fullscreen mode

Newman은 테스트 실패 시 0이 아닌 종료 코드를 반환하므로, 파이프라인 실패 조건을 별도로 작성할 필요가 없습니다.

적합한 경우

  • 팀이 이미 Postman 컬렉션을 사용 중일 때
  • GUI에서 만든 테스트를 CI에서 재사용하고 싶을 때
  • Postman 환경 변수와 테스트 스크립트를 그대로 유지하고 싶을 때

한계

  • Node.js 기반 도구입니다.
  • Postman 컬렉션 형식에 의존합니다.
  • 테스트 작성의 중심은 여전히 Postman GUI입니다.

Apidog CLI: 시각적으로 만든 시나리오를 헤드리스로 실행

Apidog CLI는 Apidog에서 설계한 테스트 시나리오를 터미널과 CI에서 실행하는 apidog-cli npm 패키지입니다.

시나리오 구성, 요청 연결, 변수 추출, 검증 작성은 Apidog의 시각적 편집기에서 수행합니다. 이후 CLI는 해당 시나리오를 헤드리스로 실행하고 종료 코드로 결과를 반환합니다.

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>

# Apidog 시나리오의 CI/CD 탭에서 생성된 명령을 복사합니다
apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

시나리오 ID와 환경 ID를 직접 추측하지 마세요. Apidog에서 테스트 시나리오를 연 뒤 CI/CD 탭으로 이동하면 ID가 채워진 apidog run 명령을 복사할 수 있습니다.

터미널 출력과 JUnit 리포트를 함께 사용하려면 다음처럼 실행합니다.

apidog run -t <scenario_id> -e <env_id> -r cli,junit
Enter fullscreen mode Exit fullscreen mode
  • 모든 검증이 통과하면 종료 코드 0을 반환합니다.
  • 검증이 실패하면 0이 아닌 종료 코드로 종료합니다.
  • 출력에는 agentHints.nextSteps를 포함하는 구조화된 JSON이 포함되어 AI 코딩 에이전트가 읽고 다음 작업을 수행하기에도 적합합니다.

적합한 경우

  • 시각적 편집기에서 복잡한 다단계 API 시나리오를 작성할 때
  • 같은 시나리오를 로컬 터미널, CI, 에이전트 환경에서 실행해야 할 때
  • 종료 코드와 리포트를 사용해 파이프라인 게이트를 구성할 때

한계

  • curl이나 xh 같은 순수 HTTP 클라이언트가 아닙니다.
  • Apidog 프로젝트에 저장된 시나리오를 실행하는 통합 플랫폼 방식입니다.
  • Apidog는 오픈 소스가 아니지만 무료 등급과 CLI를 제공합니다.

자세한 사용법은 Apidog CLI 완전 가이드, apidog run 명령 참조, Apidog CLI로 명령줄에서 REST API 테스트하는 방법을 참고하세요.

선택 방법

도구 선택은 “요청 하나 보내기”를 얼마나 넘어야 하는지에 따라 결정됩니다.

도구 최고의 용도 설치 오픈 소스? 참고
curl 일회성 요청, 스크립트 사전 설치됨 예 (MIT/curl) 보편적, 검증은 직접 구현
HTTPie 읽기 쉬운 수동 요청 pip install httpie 예 (BSD-3) 친숙한 문법, Python 런타임
xh HTTPie 느낌의 빠른 요청 brew install xh 예 (MIT) 단일 Rust 바이너리
Hurl 일반 텍스트 HTTP 테스트 brew install hurl 예 (Apache-2.0) --test로 CI 게이트 구성
Step CI 다단계 YAML 흐름 npm i -g stepci 예 (MPL-2.0) REST/GraphQL/gRPC, Node 런타임
k6 부하 및 성능 테스트 brew install k6 예 (AGPL-3.0) JS 스크립트, 임계값 위반 시 실패
Newman CI의 Postman 컬렉션 npm i -g newman 예 (Apache-2.0) Postman JSON 헤드리스 실행
Apidog CLI 시각적으로 만든 시나리오 실행 npm i -g apidog-cli 아니요 (무료 등급) 종료 코드 게이트, 에이전트 친화적 JSON

빠른 수동 호출에는 curl 또는 xh부터 시작하세요. 검증을 Git에 보관하고 CI에서 실행해야 한다면 Hurl이 적합합니다. 로그인과 토큰 재사용 같은 다단계 흐름은 Step CI를 검토할 수 있습니다. 성능 문제가 핵심이면 k6를 사용하고, 테스트가 이미 Postman 컬렉션에 있다면 Newman이 가장 직접적인 선택입니다.

복잡한 시나리오를 시각적으로 구성한 뒤 여러 실행 환경에서 헤드리스로 사용하려면 Apidog CLI를 선택하세요. GUI 없이 테스트를 실행하는 방식 자체를 더 살펴보려면 헤드리스 API 테스트 도구를 참고하세요.

경량 CLI 도구가 특히 유용한 상황

경량 CLI 도구는 GUI 전환 비용이 불필요한 상황에서 가장 효과적입니다.

  • 터미널에서 개발과 디버깅을 계속할 때
  • CI에서 사람 개입 없이 API 테스트를 실행할 때
  • AI 에이전트가 명령을 실행하고 결과를 해석해야 할 때
  • 컨테이너나 임시 환경에서 설치 비용을 최소화해야 할 때

curl과 xh는 수동 요청 루프를 빠르게 유지합니다. Hurl과 Step CI는 임시 호출을 재현 가능한 테스트로 바꿉니다. k6는 부하와 성능 질문에 답하고, Newman은 Postman에서 이미 작성한 테스트를 실행합니다.

Apidog CLI는 테스트 작성과 실행 환경을 분리합니다. Apidog에서 시나리오를 한 번 구성한 뒤 apidog run으로 터미널, CI 또는 에이전트에서 실행할 수 있습니다. Apidog를 다운로드한 후 시나리오 하나를 만들고, 생성된 apidog run 명령을 CI 설정에 추가해 종료 코드 기반 게이트를 구성해 보세요.

Top comments (0)