Newman에서 Postman CLI로 전환할 때 주의점
3줄 요약
- Newman의 마지막 릴리스는 2026-01-16 v6.2.2이고 내용은 의존성 갱신 한 줄입니다. 실제 소스 코드는 2024-08-20 이후 바뀌지 않았습니다.
- Postman CLI는 같은 기간 활발히 나오지만, 컬렉션을 v3 YAML로 바꾸는 순간 리포터가
cli하나만 남습니다. CI에서 JUnit XML을 파싱하고 있다면 그 시점에 끊깁니다. - 오늘은 갈아타지 마시고, 아래 점검 스크립트로 우리 컬렉션이 v2.1 JSON인지·파일 업로드 요청이 있는지·커스텀 리포터를 쓰는지 먼저 세어 보시면 됩니다.
작년에 만든 API 회귀 파이프라인이 아직 잘 돌고 있었습니다. 컬렉션 JSON을 저장소에 넣어 두고, CI에서 newman run 한 줄로 돌리고, JUnit XML을 GitHub Actions가 파싱해 실패한 요청 이름을 PR 화면에 띄우는 구조입니다. 잘 도는 걸 굳이 건드릴 이유가 없어서 반 년쯤 잊고 지냈습니다. 그러다 팀에서 Postman 앱을 최신 버전으로 올린 뒤 "컬렉션을 내보냈는데 Newman이 못 읽는다"는 말이 나왔습니다.
찾아보니 갈림길이 세 갈래였습니다. Newman을 그대로 두고 예전 포맷으로 내보내기를 계속하거나, Postman CLI로 갈아타되 컬렉션 포맷은 유지하거나, Postman CLI로 가면서 컬렉션까지 새 포맷으로 옮기거나. 셋 다 "된다"고 적혀 있어서 겉으로는 골라도 그만인 것처럼 보였습니다.
먼저 결론을 적겠습니다. 제 판단으로는 오늘 당장 갈아탈 이유는 없고, 갈아탄다면 컬렉션 포맷은 마지막에 손대야 합니다. 세 번째 갈래인 v3 YAML 전환에서 리포터가 cli 하나만 남기 때문입니다. CI가 XML을 파싱해 결과를 보여 주고 있다면 그 화면이 통째로 비게 됩니다. 아래에서 숫자로 확인한 것과, 직접 옮겨 보며 걸린 지점을 순서대로 적겠습니다.
1. Newman이 멈춘 지점을 숫자로 확인했습니다
말로 "유지보수가 느려졌다"고 하면 감각의 문제로 들립니다. npm 레지스트리와 GitHub 태그 페이지에서 직접 세어 봤습니다.
릴리스 간격이 17개월이었습니다
npm 레지스트리의 time 필드를 그대로 읽으면 이렇습니다.
# 레지스트리 메타데이터에서 릴리스 시각만 뽑습니다
# jq가 없으면 python3 -c 로 대체하셔도 결과는 같습니다
curl -s https://registry.npmjs.org/newman \
| jq -r '.time | to_entries[] | select(.key|test("^[0-9]")) | "\(.key)\t\(.value)"' \
| sort -k2 | tail -5
# 6.1.3 2024-06-10T02:21:43.254Z
# 6.2.0 2024-08-16T14:45:59.770Z
# 6.2.1 2024-08-20T10:36:11.364Z
# 6.2.2 2026-01-16T20:32:58.094Z ← 직전 릴리스와 약 17개월 간격
6.2.1에서 6.2.2 사이가 2024-08-20에서 2026-01-16까지, 대략 열일곱 달입니다. 그리고 6.2.2 릴리스 커밋의 CHANGELOG 변경분은 chores: 아래 - Update dependencies 단 한 줄입니다. 기능 추가도 버그 수정도 없습니다.
실제 코드는 2년 넘게 그대로입니다
저장소의 디렉터리별 최신 커밋을 보면 더 분명합니다. package.json과 CHANGELOG.yaml은 2026-01-16이지만, 실제 구현이 들어 있는 lib 디렉터리는 2024-08-20에 멈춰 있습니다. README는 2024-01-16이 마지막입니다. 즉 6.2.2는 의존성 버전만 올려 다시 패키징한 릴리스입니다.
| 항목 | Newman 6.2.2 | Postman CLI 1.52.0 |
|---|---|---|
| 최신 릴리스일 (npm) | 2026-01-16 | 2026-08-31 |
| 직전 릴리스와 간격 | 약 17개월 (6.2.1은 2024-08-20) | 4일 (1.51.0은 2026-08-27) |
| 최근 30일 릴리스 수 | 0 | 8 (1.46.0 ~ 1.52.0, 08-12 ~ 08-31) |
| npm 직접 의존성 | 21개 | 0개 (단일 바이너리 다운로드) |
| 최신 릴리스 내용 | Update dependencies 한 줄 |
— |
| 라이선스 표기 | Apache-2.0 |
npm 메타데이터에 표기 없음 |
조회 시각: 2026-09-02 KST. npm 레지스트리와 github.com 개별 태그·커밋 페이지에서 확인했습니다. GitHub의 /releases 목록 페이지는 캐시가 오래된 경우가 있어 개별 태그 페이지로 대조했습니다.
의존성 21개는 그 자체로 논점이 됩니다
Newman은 postman-runtime, postman-request, lodash, commander 등 직접 의존성만 21개를 끌고 옵니다. 전이 의존성까지 세면 CI 컨테이너 안에 수백 개 패키지가 들어갑니다. Postman CLI는 npm으로 설치해도 실제로는 서명된 바이너리를 내려받는 방식이라 dependencies가 비어 있습니다. 공급망 점검을 하는 조직이라면 이 차이가 결정에 들어갈 수 있습니다. 다만 저희처럼 4~6명 규모에서 사내 API만 도는 파이프라인이라면 이것만으로 전환을 정당화하기는 어렵다고 봅니다.
2. Postman이 실제로 한 말과, 하지 않은 말
여기가 헷갈리기 쉬운 부분이라 원문 표현을 그대로 옮기겠습니다.
공식 블로그는 "더 이상 유지보수하지 않는다"고 적었습니다
Postman 공식 블로그의 Working with the Postman CLI 글(article:published_time 기준 2026-04-28)에 비교 표가 있고, Maintained by 행의 Newman 칸이 No longer maintained입니다. 본문에도 이렇게 적혀 있습니다.
"We recommend that you always use the Postman CLI and move away from Newman, as we no longer maintain Newman."
그러나 "deprecated"라는 단어는 어디에도 없습니다
저장소와 문서를 뒤졌지만 Newman에 대해 deprecated나 maintenance mode라는 단어를 쓴 공식 문장은 찾지 못했습니다. GitHub 저장소는 아카이브 상태가 아니고, README에도 폐기 고지가 없습니다. 오픈 이슈 255건과 오픈 PR 81건이 그대로 쌓여 있을 뿐입니다.
한 가지 더 주의할 점이 있습니다. 2023-04-24자 Postman 블로그에는 "There are no plans to deprecate Newman"이라는 문장이 아직 살아 있고 검색 상위에 뜹니다. 2026-04-28 글이 이를 뒤집었으므로, 팀에 공유하실 때 어느 쪽이 최신인지 날짜를 같이 적어 주시는 편이 좋습니다.
문서는 "호환되지 않는다"는 쪽으로 말합니다
learning.postman.com의 마이그레이션 문서(2026-09-02 확인 시점)는 폐기 대신 제약을 나열합니다. 핵심 문장은 이것입니다.
"Newman only supports the v2.1 JSON format."
Postman v12 이후의 Local View·Native Git 워크플로가 v3 YAML을 쓰기 때문에, 그 환경에서 만든 컬렉션은 Newman이 아예 읽지 못합니다. 팀에서 "내보냈는데 Newman이 못 읽는다"고 했던 게 정확히 이 지점이었습니다.
팀에 공유하거나 의사결정 문서에 적을 때 어느 표현까지 쓸 수 있는지 정리하면 이렇습니다.
| 표현 | 근거가 있는가 | 출처 |
|---|---|---|
| "Postman이 더 이상 유지보수하지 않는다고 밝혔다" | 있음 | 공식 블로그 2026-04-28, No longer maintained |
| "Postman CLI가 권장 도구다" | 있음 | 마이그레이션 문서, the recommended command-line tool |
| "v3 YAML 컬렉션은 Newman이 못 읽는다" | 있음 | 마이그레이션 문서, only supports the v2.1 JSON format |
| "Newman이 deprecated 선언됐다" | 없음 | 저장소·문서·블로그 어디에도 해당 단어 없음 |
| "Newman은 maintenance mode다" | 없음 | 1차 소스 확인 실패 |
| "Postman은 Newman을 폐기할 계획이 없다" | 뒤집힘 | 2023-04-24 블로그. 2026-04-28 글이 대체 |
3. 갈아탈 때 무엇이 끊기는가 — 함정 세 가지
문서를 읽고 실제로 옮겨 보면서 세 곳에서 멈췄습니다. 순서대로 적겠습니다.
첫 번째 함정 — v3 YAML로 옮기면 리포터가 하나만 남습니다
postman collection run의 --reporters 옵션은 cli, json, junit, html 네 가지를 지원한다고 적혀 있습니다. 그런데 같은 문서에 조건이 붙어 있습니다.
"Only the
clireport output is supported for HTTP, gRPC, and GraphQL collections in v3 format (YAML)."
즉 컬렉션을 v3로 마이그레이션하는 순간 --reporters junit이 의미를 잃습니다. 저희 파이프라인은 JUnit XML을 GitHub Actions가 읽어 실패한 요청 이름을 요약에 올리는 구조였는데, 이걸 그대로 두면 요약 칸이 빕니다. 제 해석으로는 이것이 전환 비용의 대부분입니다. 도구를 바꾸는 것보다 결과를 읽는 쪽을 다시 만드는 게 훨씬 비쌉니다.
# v2.1 JSON 그대로 두면 junit 리포터가 살아 있습니다
postman collection run ./collections/api-regression.json \
-e ./env/staging.json \
--reporters cli,junit \
--bail failure
# v3 YAML로 옮기면 아래는 cli 출력만 남습니다
postman collection migrate ./collections/api-regression.json --output ./postman/collections
postman collection run ./postman/collections/api-regression # --reporters junit 이 의미 없음
두 번째 함정 — Node.js 라이브러리로는 못 씁니다
앞서 인용한 2026-04-28 블로그의 비교 표에서 Usable as a Node.js library 행이 Newman은 Yes, Postman CLI는 No (you can npm install)입니다. Newman은 require('newman')으로 감싸 커스텀 리포터를 붙이거나 결과 객체를 직접 가공하는 팀이 많습니다. newman-reporter-htmlextra 같은 서드파티 리포터도 이 구조 위에 있습니다. Postman CLI로 가면 그 생태계를 통째로 버리고 표준 출력이나 파일 산출물을 파싱하는 방식으로 다시 짜야 합니다.
세 번째 함정 — 클라우드 리포팅을 켜는 순간 CI에 키가 들어갑니다
Postman CLI는 로컬 파일 경로로 실행하면 로그인 없이 돌아갑니다. 여기까지는 Newman과 같습니다. 그런데 실행 결과를 Postman 클라우드로 보내려면 postman login으로 로그인하고 컬렉션을 ID로 지정해야 합니다. 파일 경로로 돌리면 결과가 올라가지 않습니다.
# (1) 로컬 파일 실행 — 로그인 불필요, 결과는 터미널에만
postman collection run ./collections/api-regression.json -r cli,junit
# (2) 클라우드 리포팅 — 로그인 + 컬렉션 ID 필요
postman login --with-api-key "$POSTMAN_API_KEY"
postman collection run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 \
-e "$POSTMAN_ENV_UID" --report-events
(2)를 고르면 CI 시크릿에 Postman API 키가 하나 늘고, 컬렉션의 정본이 저장소가 아니라 Postman 워크스페이스로 옮겨 갑니다. 리뷰와 롤백이 Git 밖으로 나가는 셈입니다. 저는 이 교환이 4~6명 팀에는 손해라고 봅니다.
갈아타도 그대로인 것과 오히려 나빠지는 것
전환하면 다 좋아진다고 생각하기 쉬운데, 확인해 보니 그렇지 않은 항목이 있었습니다.
| 항목 | Newman 6.2.2 | Postman CLI 1.52.0 |
|---|---|---|
| 로컬 JSON 파일만으로 오프라인 실행 | 가능 | 가능 (파일 경로 지정 시) |
| 컬렉션 v2.1 JSON | 지원 | 지원 |
| 컬렉션 v3 YAML | 불가 | 지원 |
| JUnit XML 리포터 | 지원 | v2.1은 지원 / v3는 cli만 |
| OAuth 2.0 인증 | 미지원 | 미지원 |
| 반복 데이터 파일 (CSV·JSON) | -d 지원 |
--iteration-data 지원 |
| 작업 디렉터리 파일을 body로 업로드 | 지원 | 불가 — 테스트 데이터로 업로드 필요 |
| Node.js 라이브러리로 임베드 | 지원 | 불가 |
| 커스텀·서드파티 리포터 | 있음 | 없음 |
OAuth 2.0은 양쪽 다 안 됩니다. "Newman이 오래돼서 OAuth가 안 되는 것"이라고 생각하고 갈아타면 같은 자리에서 다시 막힙니다. 파일 업로드 요청도 마찬가지로, Newman에서는 되던 것이 Postman CLI에서는 막힙니다.
4. 도입 난이도 / 유지보수 비용 / 팀 학습곡선
세 갈래를 같은 잣대로 놓고 보겠습니다. 기준은 QA 4~6명, 자동화 초기 단계, 컬렉션 2~3개, CI는 GitHub Actions입니다.
| 선택지 | 도입 난이도 | 유지보수 비용 | 팀 학습곡선 | 언제 고르나 |
|---|---|---|---|---|
| A. Newman 유지 | 없음 (변경 0) | 중간 — 보안 패치가 안 오고 v3 컬렉션은 못 읽음 | 없음 | 컬렉션이 v2.1이고 CI 리포팅이 안정적일 때 |
| B. Postman CLI + v2.1 JSON | 낮음 — 설치 한 줄, 명령어 대체 | 낮음 — 릴리스가 활발하고 리포터도 유지 | 낮음 — 옵션명이 거의 같음 | 지금 옮긴다면 이 칸 |
| C. Postman CLI + v3 YAML | 높음 — 포맷 변환 + 리포팅 재설계 | 초기 높음, 이후 낮음 | 중간 — Native Git 개념 학습 필요 | Postman v12 Local View·Native Git을 실제로 쓸 때만 |
B는 실제로 해보니 반나절이면 됩니다. 설치는 한 줄이고, -e, -d, -r, -k, -n 같은 축약 옵션이 Newman과 겹칩니다.
# 설치 — Node가 있으면 npm, 없으면 스크립트
npm install -g postman-cli
# 또는
curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
postman --version # 두 방식으로 모두 깔면 PATH 순서에 따라 다른 바이너리가 잡힙니다
which postman # 충돌이 의심되면 이걸로 확인하십시오
C는 성격이 다릅니다. 포맷 변환 자체는 postman collection migrate 한 줄이지만, 그 뒤에 리포팅을 다시 만드는 일이 남습니다. 저는 이 작업을 "도구 교체"가 아니라 "리포팅 재설계"라는 이름으로 백로그에 올려야 한다고 봅니다. 이름을 잘못 붙이면 반나절짜리로 잡혔다가 스프린트를 먹습니다.
전환 전에 우리 컬렉션부터 세어 보십시오
옮기기 전에 무엇이 걸릴지 5분이면 알 수 있습니다.
#!/usr/bin/env bash
# 전환 전 점검 — 컬렉션 디렉터리를 인자로 넘깁니다
# 예: ./precheck.sh ./collections
set -euo pipefail
DIR="${1:-./collections}"
echo "== 1) 컬렉션 포맷 (v2.1 JSON인지) =="
for f in "$DIR"/*.json; do
ver=$(jq -r '.info.schema // "schema 없음"' "$f")
printf " %-40s %s\n" "$(basename "$f")" "$ver"
done
echo "== 2) 파일 업로드 요청 (Postman CLI에서 막힙니다) =="
jq -r '[.. | objects | select(.mode? == "file")] | length' "$DIR"/*.json
echo "== 3) OAuth 2.0 사용 (양쪽 다 미지원) =="
jq -r '[.. | objects | select(.auth?.type? == "oauth2")] | length' "$DIR"/*.json
echo "== 4) 커스텀 리포터 의존 (Node 라이브러리 방식) =="
grep -rn "newman-reporter-\|require('newman')\|require(\"newman\")" \
--include="*.js" --include="*.json" --include="*.yml" . || echo " 없음"
echo "== 5) CI가 JUnit XML을 읽고 있는가 =="
grep -rn "junit\|test-results\|publish-unit-test" .github/workflows/ || echo " 없음"
2번이 0이 아니면 C는 물론 B로 갈 때도 검토가 필요하고, 5번에 결과가 나오면 C로 갈 때 그 워크플로를 먼저 다시 설계해야 합니다.
5. 권할 만한 경우 / 권하지 않는 경우
정리하면 이렇습니다.
권할 만한 경우 (B로 옮기십시오)
- 컬렉션이 v2.1 JSON이고 저장소에 있으며, CI가 파일 경로로 실행하고 있을 때. 명령어만 바꾸면 되고 리포터도 그대로 살아 있습니다.
- 보안팀이 CI 컨테이너의 npm 의존성 목록을 문제 삼을 때. 21개 직접 의존성이 0개가 됩니다.
- Postman 앱을 v12로 올릴 계획이 이미 잡혀 있을 때. 어차피 만나게 될 문제라면 리포팅이 안정적인 지금 도구만 먼저 바꿔 두는 편이 낫습니다.
권하지 않는 경우
- CI가 JUnit XML로 결과를 읽고 있고 v3 YAML까지 한 번에 가려 할 때. 리포터가
cli하나만 남습니다. 도구 교체와 포맷 변환을 같은 PR에 넣지 마십시오. require('newman')으로 감싼 리포팅 코드나 서드파티 리포터가 있을 때. 이건 다시 짜는 일이지 옮기는 일이 아닙니다.- 파일 업로드를 검증하는 요청이 있을 때. Postman CLI는 작업 디렉터리의 파일을 body로 보내지 못합니다.
- 컬렉션의 정본을 Git에 두고 싶을 때. 클라우드 리포팅을 켜면 정본이 워크스페이스 쪽으로 기웁니다.
- 단지 "유지보수가 멈췄다니 불안해서"가 이유일 때. Newman은 지금도 돌아갑니다. 불안은 근거가 아니고, 전환에는 위에 적은 실제 비용이 붙습니다.
이 글의 한계
Postman 문서 페이지들은 게시일·수정일 표기가 없어 "2026-09-02 확인 시점"까지만 말할 수 있습니다. 요금제 페이지도 마찬가지입니다. 그리고 제가 옮겨 본 건 컬렉션 두 개짜리 파이프라인이라, 컬렉션이 수십 개이고 워크스페이스 협업이 중심인 팀에서는 판단이 달라질 수 있습니다.
오늘 바로 할 수 있는 것
□ npm registry에서 우리가 쓰는 newman 버전과 6.2.2를 대조한다
□ 위 precheck.sh 를 돌려 5개 항목의 개수를 적는다
□ 2번(파일 업로드)과 5번(JUnit)이 0이면 B 전환을 스프린트 항목으로 올린다
□ 0이 아니면 "리포팅 재설계"라는 별도 항목으로 쪼갠다
□ Postman 앱 v12 업그레이드 일정과 이 작업의 선후를 팀에 공유한다
댓글
댓글 쓰기