[Postman] 요청 보내기만 쓰고 있다면 놓치는 3가지

개발자 도구 · API & DB

[Postman] 요청 보내기만 쓰고 있다면 놓치는 3가지

Postman을 요청 하나 만들어 Send 누르는 용도로만 쓰는 경우가 많은데, 그 위층에 환경변수·컬렉션 러너·프리리퀘스트 스크립트라는 세 가지 기능이 더 있습니다. dev와 운영 서버 전환, 같은 요청의 반복 실행, 요청 직전 값 가공을 각각 담당합니다. 이 글에서는 세 기능을 켜는 위치, 핵심 사용법, 미리 알아두면 좋은 제약을 공식 문서 기준으로 정리합니다.

손으로 하던 반복 작업 세 가지를 도구가 대신합니다

API를 테스트하다 보면 요청 자체보다 그 주변 작업에 손이 많이 갑니다. dev 서버를 보다가 staging을 확인하려고 URL을 일일이 고치고, 테스트 케이스 10개를 한 건씩 Send 누르고, 만료된 토큰을 다른 요청에서 복사해 헤더에 붙여넣는 식입니다.

Postman은 이 세 가지를 각각 별도 기능으로 해결합니다. 전부 추가 설치 없이 기본 화면 안에 들어 있습니다.

손으로 하던 일	담당 기능
서버 바뀔 때마다 URL·키 직접 수정	환경변수 (Environments)
테스트 케이스를 한 건씩 Send	컬렉션 러너 (Collection Runner)
토큰·타임스탬프를 복사해 붙여넣기	프리리퀘스트 스크립트 (Pre-request)

환경변수 — dev와 운영 전환이 클릭 한 번이 됩니다

환경(Environment)은 변수 묶음입니다. 같은 변수 이름에 환경마다 다른 값을 넣어 두고, 활성 환경만 바꿔서 같은 요청을 다른 서버로 보내는 구조입니다.

환경 만들고 전환하기

사이드바의 추가 아이콘에서 Environments를 선택하거나, 워크스페이스 우측 상단의 환경 선택기에서 추가 아이콘을 눌러 만듭니다. 환경 이름을 정하고 변수명과 값을 입력하면 자동 저장됩니다. 예를 들어 dev 환경과 production 환경을 만들고 둘 다 base_url이라는 변수를 넣되 값만 다르게 두는 식입니다.

활성 환경 전환은 우측 상단 환경 선택기에서 고르거나, 사이드바 Environments 목록에서 환경 옆 체크마크 아이콘을 누르면 됩니다.

변수 참조 문법

요청 URL·헤더·본문 어디서든 이중 중괄호로 참조합니다. URL에 다음처럼 쓰면 활성 환경의 값으로 치환됩니다.

GET {{base_url}}/api/v1/orders/{{order_id}}

// 스크립트에서 읽고 쓸 때
pm.environment.get("base_url");
pm.environment.set("order_id", "12345");

변수 값은 기본적으로 로컬에만 남습니다

변수에 입력한 값은 본인 로컬 Postman 인스턴스에서 요청을 보낼 때 쓰이고, Postman 클라우드로 동기화되거나 팀에 공유되지 않는 것이 기본 동작입니다. 팀과 값을 공유하려면 별도로 공유 값을 설정해야 하고, 이때는 클라우드에 동기화됩니다. API 키처럼 민감한 값은 변수명 옆 아이콘으로 Mark as sensitive 처리를 할 수 있습니다.

컬렉션 러너 — 요청 묶음을 데이터 파일로 반복 실행합니다

컬렉션 러너는 컬렉션이나 폴더 안의 요청들을 순서대로 한 번에 실행하는 기능입니다. 사이드바에서 컬렉션을 고른 뒤 Run 버튼을 누르고, Functional 탭에서 Run manually를 선택하면 실행 설정 화면이 나옵니다.

실행 옵션

• Iterations — 컬렉션 전체를 몇 번 반복할지 지정합니다.
• Delay — 요청 사이 간격을 밀리초 단위로 둡니다. 호출 제한이 있는 서버를 칠 때 씁니다.
• Persist responses for a session — 응답 헤더와 본문을 기록해 실행이 끝난 뒤 검토할 수 있게 합니다.
• Advanced settings에서 오류 발생 시 실행 중지, 변수값 유지, 쿠키 사용 제외 등을 켤 수 있습니다.

요청은 컬렉션에 나열된 순서대로 실행되고, 실행 설정 화면에서 드래그로 순서를 바꿀 수 있습니다. 결과 화면에서는 Passed·Failed·Skipped 탭으로 테스트 결과를 필터링해서 봅니다.

데이터 파일로 케이스 100개를 한 번에

러너의 진짜 쓸모는 데이터 파일과 묶을 때 나옵니다. CSV나 JSON 파일을 올리면 파일의 행 하나가 반복(iteration) 하나가 되고, 각 행의 값이 요청 안의 변수에 채워집니다. 경계값·오류 케이스를 행으로 쭉 적어 두면 같은 요청이 케이스 수만큼 실행되는 구조입니다.

order_id,coupon_code,expected_status
1001,WELCOME10,200
1001,EXPIRED99,400
9999,WELCOME10,404

CSV는 첫 행이 변수명이고 그 아래 행들이 데이터입니다. 요청 본문이나 URL에서 {{coupon_code}}처럼 변수명으로 참조하면 반복마다 해당 행의 값이 들어갑니다.

프리리퀘스트 스크립트 — 요청 직전에 JavaScript가 돌아갑니다

프리리퀘스트 스크립트는 요청이 전송되기 전에 실행되는 JavaScript입니다. 변수·파라미터·헤더·본문 데이터를 동적으로 설정하거나 콘솔에 로그를 남기는 용도로 씁니다. 요청을 선택하고 Scripts 탭의 Pre-request 탭에 코드를 적으면 됩니다.

붙이는 위치가 세 군데입니다

개별 요청 외에 폴더와 컬렉션에도 같은 방식으로 붙일 수 있습니다. 컬렉션에 붙이면 그 컬렉션의 모든 요청 전에, 폴더에 붙이면 폴더 바로 아래 요청 전에 실행됩니다. 인증 토큰 세팅처럼 모든 요청에 공통인 로직은 요청마다 복사하지 말고 컬렉션 레벨에 한 번만 두는 것이 관리가 쉽습니다.

// 컬렉션 레벨 Pre-request 예시: 요청마다 타임스탬프 갱신
pm.environment.set("request_ts", new Date().toISOString());

// 이후 요청 헤더에서
// X-Request-Time: {{request_ts}}

컬렉션 러너와 묶으면 앞 요청의 응답값을 받아 다음 요청에 넘기는 흐름도 만들 수 있습니다. 로그인 요청의 응답에서 토큰을 꺼내 변수에 저장하고, 뒤의 요청들이 그 변수를 참조하는 패턴이 대표적입니다.

미리 알아두면 좋은 함정

• 수동 컬렉션 실행에 월 한도가 있습니다. Postman 플랜별로 월별 컬렉션 실행 횟수 제한이 있고, 이 제한은 수동 실행(Run manually)에 적용됩니다. 반복(iteration)이 여러 번이어도 실행 1회로 계산됩니다.
• CSV 형식 규칙이 엄격합니다. 첫 행은 반드시 변수명이어야 하고, 모든 행의 컬럼 수가 같아야 하며, 줄 끝은 Unix 형식이어야 합니다. 러너가 파일을 못 읽으면 이 세 가지부터 확인하는 것이 빠릅니다.
• 공유 값 설정 전에 내용물을 확인해야 합니다. 변수 값을 팀과 공유하도록 설정하면 클라우드에 동기화됩니다. 토큰이 든 변수를 공유 값으로 넣으면 그대로 팀에 노출되는 셈이라, 민감한 값은 로컬 값으로만 두고 Mark as sensitive 처리를 하는 편이 안전합니다.
• 팀 환경 편집에는 Editor 역할이 필요합니다. 환경을 편집하고 공유 값을 바꾸려면 해당 환경에 대한 Editor 역할이 있어야 합니다.
• 컬렉션 스크립트는 모든 요청에 걸립니다. 컬렉션 레벨 프리리퀘스트는 하위 모든 요청 전에 실행되므로, 특정 요청에만 필요한 로직을 컬렉션에 두면 나머지 요청까지 영향을 받습니다.

이미 깔려 있다면 환경변수부터 시작하면 됩니다

세 기능 모두 별도 설치가 없어서 도입 비용은 사실상 학습 시간뿐입니다. 순서를 정한다면 환경변수가 먼저입니다. base_url 하나만 변수로 빼도 서버 전환 때마다 URL을 고치는 일이 사라지고, 나머지 두 기능이 전부 변수를 기반으로 동작하기 때문입니다.

그다음이 컬렉션 러너입니다. 반복 검증할 케이스가 쌓여 있는 API라면 CSV 한 장으로 회귀 테스트 묶음이 생깁니다. 프리리퀘스트 스크립트는 토큰 갱신처럼 매번 손으로 하던 전처리가 생겼을 때 그 시점에 도입하면 됩니다.

참고 환경변수와 프리리퀘스트 스크립트는 무료 플랜에서도 제한 없이 쓸 수 있지만, 수동 컬렉션 실행은 플랜별 월 한도가 있습니다. 팀 단위로 러너를 자주 돌릴 계획이라면 현재 플랜의 한도를 먼저 확인하는 것이 좋습니다.

Sources

Postman Docs — Group sets of variables using environments Postman Docs — Edit and set environment variables Postman Docs — Test your API using the Collection Runner Postman Docs — Write pre-request scripts

이 글은 직접 사용기가 아니라 공식 문서를 기준으로 한 객관 정리입니다. 메뉴 구성과 플랜별 제한은 버전·플랜에 따라 다를 수 있으니 공식 문서를 함께 확인하세요.