Apidog CLI vs Newman: CI에서 API 테스트 실행 (2026)

API 테스트는 노트북에서 통과합니다. 더 어려운 질문은 사람이 아무것도 클릭하지 않고 모든 풀 리퀘스트, 모든 병합, 그리고 모든 야간 빌드에서 실행되는지 여부입니다. 그 작업은 명령줄 러너의 역할입니다. 이미 작성한 테스트를 가져와서 파이프라인 내에서 헤드리스로 실행하고, CI가 읽을 수 있는 상태 코드로 종료하며, 대시보드가 파싱할 수 있는 보고서를 작성합니다. GUI도, 수동 단계도 없으며, 실행을 건너뛸 핑계도 없습니다.

수년 동안 이러한 요구에 대한 기본 답변은 Postman의 오픈 소스 명령줄 컬렉션 러너인 Newman이었습니다. 견고하고 잘 알려진 도구이며, 여전히 많은 팀이 이를 먼저 선택합니다. 그러나 Postman 대신 Apidog에서 테스트를 작성하는 경우 두 번째 옵션이 있습니다: Apidog CLI는 앱에서 시각적으로 구축한 동일한 테스트 시나리오를 CI에서 헤드리스로 실행합니다. 이 기사는 두 도구에 대한 솔직하고 명령 수준의 비교입니다. Newman이 잘하는 점, Apidog CLI가 적합한 곳, 그리고 실제 파이프라인에 연결되었을 때 각각이 어떻게 느껴지는지를 다룹니다.

요약

• Newman (newman, npm install -g newman을 통해 설치)은 내보낸 Postman 컬렉션 JSON 파일을 실행합니다. 오픈 소스이며 무료이고, 디스크 또는 URL에서 컬렉션 및 환경 파일을 읽습니다. 환경, 데이터 파일, 반복 횟수, JUnit/JSON/HTML 리포터를 지원하며, 테스트가 실패하면 0이 아닌 상태 코드로 종료합니다.
• Apidog CLI (apidog-cli, 바이너리 apidog)는 액세스 토큰을 사용하여 ID로 가져온 Apidog 앱에서 설계한 테스트 시나리오를 실행합니다. 아무것도 내보내거나 JSON 파일을 수동으로 유지할 필요가 없습니다. 시각적 시나리오가 테스트이며, CLI는 앱이 하는 것과 똑같이 실행합니다.
• 둘 다 GitHub Actions, GitLab CI, Jenkins 및 Node.js가 있는 모든 곳에 연결됩니다. 둘 다 테스트 실패 시 빌드를 실패시킵니다. JUnit XML은 양쪽의 CI 대시보드에 연결되는 것입니다.
• 테스트가 이미 Postman 컬렉션으로 존재하고 새로운 계정 없이 무료로 저장소 친화적인 러너를 원한다면 Newman을 선택하세요.
• 시각적 작성, 요청 체이닝, 환경 관리, 그리고 팀이 매일 디버깅하는 동일한 시나리오와 동기화되는 데이터 기반 실행을 원한다면 Apidog CLI를 선택하세요.

실제 문제: 존재하지만 한 번도 실행되지 않는 테스트

수동으로 실행하는 테스트는 썩어 버리는 테스트입니다. 누군가 그것을 만들었고, 한 번 통과했고, 그런 다음 API가 그 아래에서 바뀌는 동안 건드려지지 않은 채 방치되었습니다. 더 많은 테스트가 그 문제를 해결하지 못합니다. 변경될 때마다 자동으로 실행되는 테스트만이 해결책입니다. 왜냐하면 파이프라인이 조치할 수 있는 통과 또는 실패 신호를 생성하기 때문입니다.

CLI 러너는 그 간극을 메웁니다. CI에서 유용하려면 세 가지를 수행해야 합니다. GUI 없이 실행되고, 무언가 실패하면 빌드가 빨간색으로 바뀌도록 0이 아닌 상태 코드로 종료하고, 검토자가 무엇이 문제인지 확인할 수 있도록 기계가 읽을 수 있는 보고서를 작성해야 합니다. Newman과 Apidog CLI는 모두 이 기준을 깔끔하게 충족합니다. 둘의 차이점은 실행 명령의 상위에 있습니다. 즉, 테스트가 어떻게 작성되었고 어디에 존재하는지에 있습니다. CI를 처음부터 설정하는 경우, CI/CD에서 API 테스트를 자동화하는 방법의 더 넓은 패턴이 이 비교와 잘 어울립니다. 여기서는 두 러너에 초점을 맞춥니다.

Newman이 잘하는 것

Newman은 그 자리를 충분히 차지했습니다. Postman의 공식 오픈 소스 동반 도구이며, 이미 Postman 컬렉션으로 테스트가 존재하는 팀에게는 "내 머신의 테스트"에서 "CI의 테스트"로 가는 가장 직접적인 경로입니다. 어떤 비교를 하기 전에 그 강점을 명확하게 언급할 가치가 있습니다.

무료이며 오픈 소스입니다. npm에서 설치하고 Node.js가 실행되는 모든 곳에서 실행할 수 있으며, 러너 자체에 대한 별도의 라이선스가 필요하지 않습니다. 컬렉션은 저장소에 커밋하거나 빌드 아티팩트로 저장하거나 URL에서 가져올 수 있는 휴대용 JSON 파일입니다. 이러한 휴대성은 실제이며, Newman이 거의 모든 파이프라인에 마찰 없이 통합될 수 있음을 의미합니다.

이미 구축한 것을 재사용합니다. 팀이 Postman에서 요청, 사전 요청 스크립트 및 테스트 어설션을 작성하는 경우, Newman은 동일한 컬렉션을 변경 없이 실행합니다. 다시 작성할 필요가 없습니다. Postman 편집기에서 작성한 스크립트는 헤드리스 실행에서도 동일하게 실행되므로 Postman 사용자의 학습 곡선이 평탄하게 유지됩니다.

설치는 단 하나의 명령입니다:

npm install -g newman

바이너리는 newman입니다. JSON 파일을 가리켜 내보낸 컬렉션을 실행합니다. 일반적으로 환경 파일과 함께 사용합니다:

newman run api-tests.postman_collection.json -e staging.postman_environment.json

이것이 핵심 루프입니다. Postman에서 컬렉션을 내보내고, JSON을 커밋하고, 실행합니다. Newman은 파일에서 요청과 어설션을 읽고 순서대로 실행합니다. 전체 설정 경로의 경우, Newman 설치 및 Postman 컬렉션 실행 방법에 대한 Apidog 자체 가이드는 내보내기-실행 흐름을 단계별로 다룹니다.

Newman은 또한 예상할 수 있는 CI 필수 기능을 지원합니다. 데이터 기반 실행은 CSV 또는 JSON 파일에서 가져옵니다:

newman run api-tests.postman_collection.json \
  -e staging.postman_environment.json \
  -d users.csv \
  -n 5

여기서 -d는 데이터 파일을 제공하고 -n은 반복 횟수를 설정하므로, 컬렉션은 각 행당 한 번 또는 고정된 횟수만큼 실행됩니다. 이들은 어떤 진지한 러너든 필요한 동일한 기본 기능이며, Newman은 수년 동안 이를 가지고 있었습니다.

Newman이 비용을 발생시키기 시작하는 지점

위에서 언급한 강점은 솔직하지만, 단일 명령이 아니라 일상적인 유지보수에서 나타나는 트레이드오프도 마찬가지입니다.

가장 큰 문제는 내보내기 단계입니다. CI의 Postman 컬렉션은 스냅샷입니다. Postman 앱에서 작성하고 디버그한 다음, 헤드리스로 실행하기 위해 JSON 파일을 내보냅니다. 누군가 앱에서 요청을 편집하고 다시 내보내는 것을 잊는 순간, 커밋된 컬렉션은 진실의 원본과 멀어집니다. 실제 API가 변경되었는데도 CI 실행은 오래된 정의에 대해 계속 통과합니다. 도구에서 둘을 다시 동기화하도록 강제하는 것은 아무것도 없습니다. 내보내기를 기억하는 사람의 책임입니다.

스크립팅은 또 다른 문제입니다. Postman 테스트 로직은 각 요청에 첨부된 JavaScript 코드 조각에 있으며, 이 스크립트에서 체이닝, 변수 추출 및 어설션이 발생합니다. 이는 유연하지만, 테스트 스위트가 수동으로 작성, 디버그 및 유지 관리해야 하는 작은 스크립트 더미라는 것을 의미합니다. 시나리오가 커질수록 소유해야 하는 스크립트 표면도 커집니다. 이는 컬렉션이 확장됨에 따라 팀이 겪는 더 넓은 패턴의 일부이며, 이에 대해서는 Postman 컬렉션 러너의 제약 사항 및 해결 방법에서 다룹니다.

이 모든 것이 Newman을 나쁜 도구로 만들지는 않습니다. 이는 Newman을 Postman의 작성 모델(스크립트 + 내보내기 단계)에 묶인 러너로 만듭니다. 그 모델이 팀에 적합하다면 Newman은 괜찮습니다. 그러나 내보내기 및 동기화 과정이 계속해서 문제가 되는 부분이라면, 그곳이 바로 다른 러너가 도움이 되는 지점입니다.

Apidog CLI가 다른 점

Apidog는 동일한 파이프라인에 대해 다른 경로를 택합니다. Apidog 앱에서 시각적으로 테스트를 구축합니다. 요청을 테스트 시나리오로 연결하고, 노코드 편집기에서 어설션을 추가하며, 한 응답에서 값을 다음 요청으로 가져와 전체 과정을 데이터 파일로 반복합니다. CLI는 이러한 시나리오의 헤드리스 실행기입니다. 별도의 파일 형식이 없으며 내보낼 것도 없습니다. Apidog 프로젝트에서 ID로 지정한 시나리오를 가져와서 앱이 하는 것과 똑같이 실행합니다.

이는 드리프트 문제를 제거합니다. 프로젝트의 시나리오가 테스트입니다. 동기화가 어긋날 내보낸 스냅샷이 없습니다. CLI가 복사본이 아닌 실시간 시나리오를 실행하기 때문입니다. 요청 체이닝과 어설션을 처리하는 시각적 빌더에서 한 번 작성하면, 동일한 시나리오가 CI에서 실행됩니다. 빠른 작성 루프와 자동화 루프가 하나의 진실 원천을 공유합니다.

설치는 하나의 npm 명령입니다:

npm install -g apidog-cli

바이너리는 apidog입니다. 일반적인 실행은 시나리오를 ID로 지정하고, 환경을 선택하며, 액세스 토큰으로 인증합니다:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,junit

이러한 ID를 수동으로 입력할 필요가 없습니다. Apidog에서 테스트 시나리오를 열고 CI/CD 탭으로 전환하여 액세스 토큰을 생성하면, Apidog가 시나리오 ID와 환경 ID가 이미 채워진 전체 명령을 생성해줍니다. 한 번 복사한 다음 토큰을 CI 비밀로 옮기고 $APIDOG_ACCESS_TOKEN으로 참조합니다. 설치된 버전이 어떤 플래그를 지원하는지 확실하지 않다면 apidog run --help를 실행하면 사용 가능한 정확한 옵션이 인쇄됩니다.

토큰 기반의 ID로 가져오기 모델은 Newman과의 가장 분명한 차이점입니다. Newman은 디스크에서 컬렉션 파일을 읽습니다. Apidog CLI는 인증을 통해 네트워크를 통해 프로젝트에 접근하여 거기에 저장된 시나리오를 실행합니다. 둘 다 틀린 것은 아닙니다. 둘은 다른 팀 설정에 적합하며, 선택은 주로 테스트가 내보낸 파일로 존재하기를 원하는지 아니면 공유 작업 공간의 라이브 시나리오로 존재하기를 원하는지에 달려 있습니다.

비교

두 가지가 눈에 뜁니다. 첫째, 두 러너 모두 환경 선택, 데이터 기반 반복, 중요한 보고서 형식, 그리고 실패 시 0이 아닌 종료 코드와 같은 CI 필수 요소를 다룹니다. 플래그 이름도 (-e, -d, -n, -r) 근접하여 근육 기억이 전환될 정도입니다. 둘째, 실제 차이는 순수한 기능이 아닙니다. 테스트가 어디에 있고 어떻게 작성되었는지에 있습니다. Newman은 스크립트로 작성된 내보낸 컬렉션을 실행합니다. Apidog는 참조를 통해 라이브 시각적 시나리오를 실행합니다. Postman 세계의 두 러너를 중심으로 한 더 심층적인 비교는 Postman CLI vs Newman에서 찾을 수 있습니다.

리포터와 종료 코드: CI가 실제로 읽는 부분

러너는 두 가지 행동을 통해 파이프라인에서 제 역할을 합니다. 작성하는 보고서와 반환하는 종료 코드입니다. 이들을 제대로 처리하면 나머지는 연결하는 문제입니다.

Newman은 -r 플래그와 쉼표로 구분된 목록으로 리포터를 선택합니다. JUnit 및 JSON은 기본으로 제공되며, HTML 리포터는 가장 일반적인 추가 기능입니다:

newman run api-tests.postman_collection.json \
  -e staging.postman_environment.json \
  -r cli,junit \
  --reporter-junit-export ./results/junit.xml

JUnit XML은 CI 대시보드가 통과 또는 실패 트리로 파싱하는 것입니다. Newman의 --bail 플래그는 첫 번째 실패 후 실행을 중지하여 스모크 테스트에서 빠른 피드백을 유지합니다. 이 플래그가 없으면 실행이 완료되고 모든 실패를 한 번에 보고합니다.

Apidog CLI는 동일한 쉼표로 구분된 -r 플래그를 사용하며 모든 것을 하나의 출력 디렉터리 아래에 작성합니다:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 \
  -r html,junit --out-dir ./apidog-reports

그것의 --on-error 플래그는 시나리오 중간 동작을 형성합니다: end는 첫 번째 실패에서 중지하며 기본값입니다. continue는 모든 단계를 실행하여 하나의 보고서에 모든 실패를 수집하며, ignore는 알려진 불안정한 단계를 건너뜁니다. 어떤 방식이든 실패하면 0이 아닌 값으로 종료합니다.

종료 코드 계약은 양쪽에서 동일하며, 핵심적인 부분입니다. 어설션이 실패하면 러너는 0이 아닌 값으로 종료합니다. CI는 그 코드를 읽고 단계를 실패로 표시하며, 작업을 실패시키고 병합 또는 배포를 차단합니다. 추가로 구성할 것은 없습니다. 둘 다 동일하게 주의해야 할 한 가지 함정은 종료 코드를 무시하는 것입니다. 실행을 셸 파이프라인으로 감싸거나 || true를 추가하면 0이 아닌 종료 코드가 무시되어 게이트가 묵묵히 작동을 멈춥니다. 그렇게 하지 마세요. 보고서 형식에 대한 더 넓은 맥락은 CSV 또는 JSON을 사용한 데이터 기반 API 테스트에서 보고서가 반복 데이터와 어떻게 연결되는지 보여줍니다.

GitHub Actions의 Newman

컬렉션이 저장소에 내보낸 파일이므로 워크플로우는 간단합니다. 코드를 체크아웃하고, Newman을 설치하고, 컬렉션을 실행하고, 실패 시에도 보고서를 업로드합니다.

name: API tests

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Newman
        run: npm install -g newman

      - name: Run API tests
        run: |
          newman run ./tests/api-tests.postman_collection.json \
            -e ./tests/staging.postman_environment.json \
            -r cli,junit \
            --reporter-junit-export ./results/junit.xml

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: newman-report
          path: ./results

컬렉션 및 환경 파일이 저장소에 커밋되어 있다면 별도의 비밀은 필요하지 않습니다. if: always() 줄은 테스트가 실패할 때에도 보고서 업로드를 계속 실행하도록 하는데, 이는 바로 보고서를 읽고 싶을 때입니다. 감수해야 할 비용은 애초에 해당 JSON 파일을 생성한 내보내기 단계와 API 변경 시 이를 새로 고쳐야 한다는 점을 기억하는 것입니다.

GitHub Actions의 Apidog CLI

Apidog 워크플로우는 동일한 형태를 가지며, 한 가지 변경 사항이 있습니다. 액세스 토큰은 저장소 비밀에서 가져오고, 파일을 가리키는 대신 ID로 시나리오를 선택합니다.

name: API tests

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

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

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r html,junit \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: ./apidog-reports

대칭성을 주목하십시오. 동일한 체크아웃, 동일한 Node 설정, 동일한 설치-실행 형태, 동일한 항상-업로드. 유일한 실제 차이점은 비밀로 연결된 토큰과 파일 경로가 아닌 ID로 선택된 시나리오입니다. 시나리오는 실시간으로 가져오기 때문에 최신 상태를 유지할 JSON 파일이 없습니다. 다른 시스템에서의 동일한 패턴에 대해서는 GitHub Actions에서 API 테스트를 자동화하는 방법에서 GitLab CI 및 Jenkins에 걸쳐 구조를 설명합니다.

선택 방법

결정은 어느 러너가 객관적으로 더 낫냐는 문제로 귀결되는 경우는 거의 없습니다. 테스트가 이미 어디에 존재하고 팀이 어떻게 유지 관리하기를 원하는지에 달려 있습니다.

테스트가 이미 Postman 컬렉션이라면 Newman을 선택하세요. 만약 스위트가 Postman에 있고, 팀이 편집기에서 테스트 스크립트를 작성하며, 새로운 계정 없이 모든 파이프라인에 통합되는 무료 오픈 소스 러너를 원한다면 Newman이 적합합니다. 컬렉션을 내보내고 JSON을 커밋하는 데 익숙하며 테스트 스크립트를 수동으로 관리하는 것을 개의치 않는 Postman 사용 팀에게 자연스러운 선택입니다. Postman 생태계 내부의 차이점에 대해서는 Newman과 Postman의 차이점에서 더 자세히 읽을 수 있습니다.

작성 속도와 단일 진실 원천이 Postman 내부에 머무는 것보다 더 중요하다면 Apidog CLI를 선택하세요. 테스트 코드를 작성하고 다시 내보내지 않고 시각적으로 테스트 시나리오를 구축하고, 요청을 연결하고, 변수를 추출하며, 동일한 시나리오를 여러 환경에서 실행하고 싶다면 Apidog가 그 마찰을 제거합니다. 하나의 작업 공간에서 디자인, 디버그, 모의 및 테스트를 실시간으로 수행하면 CLI가 구축한 정확한 시나리오를 실행합니다. Postman에서 넘어오는 팀의 경우, Apidog는 API 테스트를 위한 Postman 대안으로 마이그레이션을 지원하며, 가져오기는 한 번의 클릭으로 가능합니다.

두 도구 모두를 사용하는 답변도 있습니다. 일부 팀은 레거시 컬렉션을 실행하는 기존 Newman 단계를 유지하면서, 새롭고 더 복잡한 체인형 시나리오를 Apidog로 옮깁니다. 두 CLI는 하나의 파이프라인에서 잘 공존합니다. 이들은 별도의 종료 코드를 가진 별도의 단계이며, Newman 단계는 원하는 시점에 중단할 수 있습니다.

첫 번째 자동화된 시나리오를 설정하고 같은 날 오후에 터미널에서 실행하려면, Apidog를 다운로드하고, 테스트 시나리오를 구축한 다음, CI/CD 탭에서 생성된 명령을 복사하십시오.