Postman은 HTTP 요청을 보내고 API 동작을 확인하는 데 가장 널리 사용되는 도구 중 하나입니다. 이 도구는 브라우저 확장 프로그램으로 시작하여 빠른 GET 요청부터 CI에서 실행되는 스크립트 테스트 스위트까지 모든 것을 처리하는 완전한 데스크톱 애플리케이션으로 성장했습니다. API를 구축하거나 사용하는 경우 거의 확실하게 이 도구를 접하게 될 것입니다.
이 가이드는 Postman에서 API를 일상적으로 테스트하는 방법을 설명합니다. 요청을 보내고, 응답을 검사하고, "테스트(Tests)" 탭에 어설션을 작성하고, 스테이징과 프로덕션 환경을 전환할 수 있도록 환경을 설정하고, "컬렉션 러너(Collection Runner)"를 사용하여 전체 컬렉션을 한 번에 실행하는 방법을 배울 것입니다. 예제는 공용 API를 사용하므로 별도로 설정할 필요 없이 따라할 수 있습니다.
Postman 설정 및 첫 번째 요청 보내기
공식 사이트에서 Postman을 다운로드하여 데스크톱 앱을 설치하세요. 계정 없이 로컬 작업에 사용할 수 있지만, 로그인하면 컬렉션이 여러 장치에서 동기화됩니다. 앱을 열고 새로 만들기(New) 버튼을 클릭한 다음 HTTP 요청(HTTP Request)을 선택합니다.
요청에는 최소한 세 가지가 필요합니다: 메서드, URL, 그리고 경우에 따라 본문. 메서드 드롭다운에서 GET을 선택하고 실제 엔드포인트를 입력합니다. JSONPlaceholder 서비스는 실습에 유용합니다:
GET https://jsonplaceholder.typicode.com/users/1
보내기(Send)를 클릭합니다. 응답 패널에는 본문, 상태 코드(200 OK), 응답 시간 및 크기가 채워집니다. JSON이 포맷된 형태로 또는 서버가 보낸 원본 형태로 보려면 본문 보기를 예쁘게(Pretty), 원본(Raw), 미리보기(Preview) 사이에서 전환하세요.
POST 요청의 경우, 메서드를 변경하고 본문(Body) 탭을 연 다음 raw를 선택하고 형식 드롭다운에서 JSON을 선택하세요. 다음과 같은 페이로드를 붙여넣으세요:
{
"name": "Maria Chen",
"email": "maria.chen@example.com"
}
JSON 본문 유형을 선택하면 Content-Type: application/json과 같은 헤더가 자동으로 추가됩니다. 헤더(Headers) 탭에서 Authorization 헤더와 같이 API에 필요한 다른 모든 것을 추가할 수 있습니다. 어떤 응답 코드를 예상해야 할지 잘 모른다면, REST API가 사용해야 하는 HTTP 상태 코드에 대한 가이드가 유용한 참고 자료가 될 것입니다.
요청을 컬렉션으로 구성
단일 요청은 빠른 확인에 적합합니다. 실제 테스트는 서로 관련된 여러 요청(사용자 생성, 사용자 가져오기, 사용자 업데이트, 사용자 삭제)을 의미합니다. Postman은 이들을 컬렉션(collections)으로 묶습니다.
사이드바에서 컬렉션(Collections)을 클릭한 다음 + 아이콘을 클릭하여 새 컬렉션을 생성합니다. "사용자 API 스모크 테스트"와 같이 구체적인 이름을 지정합니다. 각 요청을 Ctrl/Cmd + S로 컬렉션에 저장하고 명확한 이름을 부여하세요. 컬렉션 내부에 폴더를 중첩하여 인증 요청과 리소스 요청 등을 분리할 수 있습니다.
컬렉션은 공유하는 단위이기도 합니다. JSON 파일로 내보내거나, 클라우드에 동기화하는 경우 링크를 공유할 수 있습니다. 팀원들은 이를 가져와서 당신과 똑같은 요청을 사용할 수 있습니다. 컬렉션 러너와 자동화된 테스트가 개별 요청이 아닌 컬렉션에서 작동하기 때문에 이것이 다른 모든 것의 기반이 됩니다.
컬렉션은 공유 동작을 포함할 수도 있습니다. Postman은 단일 요청뿐만 아니라 컬렉션 또는 폴더 수준에서 스크립트를 첨부할 수 있도록 합니다. 컬렉션에 있는 사전 요청 스크립트(pre-request script)는 그 안에 있는 모든 요청 전에 실행되며, 토큰을 새로 고치거나 타임스탬프를 찍는 데 유용합니다. 컬렉션 수준의 테스트 스크립트는 모든 요청 후에 실행되며, "응답 시간이 합리적이다"와 같이 모든 곳에서 원하는 어설션에 편리합니다. 이러한 스크립트를 한 번 정의하면 개별 요청이 고유한 부분에 집중할 수 있도록 합니다.
테스트 탭에 테스트 작성
요청을 보내면 무엇이 돌아왔는지 알 수 있습니다. 테스트(test)는 돌아온 내용이 올바른지 여부를 매번 자동으로 알려줍니다. Postman은 응답이 도착한 후 요청의 스크립트(Scripts) 영역(이전 버전에서는 테스트(Tests) 탭이라고 불림)에서 JavaScript를 실행합니다.
Postman은 어설션을 작성하기 위한 pm 객체를 노출합니다. 핵심 패턴은 pm.test(name, callback)이며, 콜백 함수는 기대치가 실패하면 예외를 발생시킵니다. 다음은 계속 사용하게 될 어설션입니다:
// Check the status code
pm.test("Status code is 200", function () {
pm.response.to.have.status(200);
});
// Check response time
pm.test("Response is under 500ms", function () {
pm.expect(pm.response.responseTime).to.be.below(500);
});
// Check a field in the JSON body
pm.test("User has the expected email", function () {
const body = pm.response.json();
pm.expect(body.email).to.eql("maria.chen@example.com");
});
// Check a header
pm.test("Content-Type is JSON", function () {
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/json");
});
어설션 구문은 Chai에서 가져왔으므로 pm.expect는 .to.eql, .to.include, .to.be.above 등을 지원합니다. 보내기(Send)를 클릭하면 테스트 결과(Test Results) 탭에 결과가 표시되며, 각 테스트는 초록색 또는 빨간색으로 나타납니다.
몇 가지 습관은 테스트를 유용하게 유지합니다. 각 pm.test 블록의 이름을 엔드포인트가 아닌 확인하는 동작에 따라 지정하면 실패 메시지가 문장처럼 읽힙니다. API 사용자를 실제로 망가뜨릴 수 있는 것들(상태 코드, 본문의 형태, 클라이언트가 의존하는 필드)을 확인하세요. 서버에서 생성된 타임스탬프와 같이 제어할 수 없는 값에 대해 어설션하는 것을 피하세요. 이러한 어설션은 사람들에게 빨간색을 무시하도록 학습시키는 불안정한 실패를 유발합니다. Postman은 또한 편집기 옆에 즉시 사용할 수 있는 어설션이 포함된 스니펫(Snippets) 패널을 제공하며, 이를 클릭하여 삽입할 수 있어 pm API를 배우는 가장 빠른 방법입니다. 어설션 설계에 대해 더 자세히 알아보려면 API 어설션과 이를 잘 작성하는 방법에 대한 분석을 참조하세요. 검사를 명명된 사례로 구성하는 더 넓은 아이디어에 대해서는 API 테스트 케이스 예제 가이드를 함께 읽어볼 가치가 있습니다.
환경 및 변수 사용
모든 요청에 https://api.staging.example.com을 하드코딩하는 것은 프로덕션을 가리켜야 할 때 고통스럽습니다. 환경(Environments)이 이 문제를 해결합니다. 환경은 이름이 지정된 변수 집합입니다.
사이드바에서 환경 아이콘을 클릭하고 "Staging"이라는 환경을 만듭니다. base_url 변수를 값 https://jsonplaceholder.typicode.com과 함께 추가합니다. 다른 base_url을 가진 "Production"이라는 두 번째 환경을 만듭니다. 이제 이중 중괄호를 사용하여 요청에서 변수를 참조합니다:
GET {{base_url}}/users/1
오른쪽 상단 드롭다운에서 활성 환경을 선택하면, {{base_url}}을 사용하는 모든 요청이 해당 환경으로 전환됩니다.
변수는 요청 간에 데이터를 전달하기도 합니다. 로그인 요청은 응답에서 토큰을 캡처하여 나중에 요청에서 사용할 수 있도록 저장할 수 있습니다:
pm.test("Save the auth token", function () {
const token = pm.response.json().token;
pm.environment.set("auth_token", token);
});
그러면 이후의 모든 요청은 Authorization: Bearer {{auth_token}}을 보낼 수 있습니다. 이러한 연결(chaining)은 리소스를 생성하고 그 존재를 확인하는 것과 같이 상태에 따라 달라지는 흐름을 테스트하는 방법입니다.
Postman에는 알아둘 만한 두 가지 관련 변수 스코프가 있습니다. 환경 변수(Environment variables)는 선택된 환경에 속하며 환경을 전환할 때 변경됩니다. 컬렉션 변수(Collection variables)는 환경과 관계없이 컬렉션에 속하며, 해당 API에 대해 일정한 값에 적합합니다. 또한 모든 곳에 적용되는 전역 변수(global variables)와 단 한 번의 실행 동안만 존재하는 수명이 짧은 지역 변수(local variables)가 있습니다. 올바른 스코프를 선택하면 값이 제자리에 유지되고 대상을 전환할 때 예상치 못한 상황을 피할 수 있습니다.
컬렉션 러너로 전체 컬렉션 실행
각 요청에서 보내기(Send)를 클릭하는 것은 금방 지루해집니다. 컬렉션 러너(Collection Runner)는 컬렉션의 모든 요청을 순서대로 실행하고, 모든 테스트를 실행하며, 합격/불합격 요약을 제공합니다.
컬렉션을 열고 실행(Run) 버튼(또는 세 점 메뉴를 클릭한 다음 컬렉션 실행(Run collection))을 클릭합니다. 러너는 요청을 순서대로 보여줍니다. 환경을 선택하고, 실행할 반복 횟수를 설정하며, 필요에 따라 데이터 파일을 첨부합니다. 실행(Run)을 클릭하면 Postman이 모든 요청을 위에서 아래로 실행하며, 각 요청의 테스트를 수행합니다.
결과 페이지에는 모든 요청에 대한 모든 어설션이 통과 및 실패 총계와 함께 나열됩니다. 이것이 당신의 회귀 테스트입니다. 배포 후에 실행하면 API가 여전히 잘 작동하는지 몇 초 안에 알 수 있습니다. 러너는 또한 이전 실행 기록을 유지하므로 오늘의 결과를 어제의 결과와 비교하고 이전에 성공했던 스위트가 언제 실패하기 시작했는지 파악할 수 있습니다.
러너에서는 순서가 중요합니다. 요청이 위에서 아래로 실행되므로, 로그인 요청을 먼저 배치하여 auth_token을 채우고, 그 아래의 모든 요청이 해당 토큰을 사용하도록 할 수 있습니다. 설정 및 정리에도 동일하게 적용됩니다: 시작 부분에서 리소스를 생성하고, 중간에 사용하고, 마지막에 삭제합니다. 잘 정돈된 컬렉션은 완전한 사용자 여정을 효과적으로 스크립트화합니다.
데이터 기반 테스트를 위해 러너에 CSV 또는 JSON 파일을 첨부하세요. 각 행은 하나의 반복이 되며, 열은 {{username}}과 같은 변수로 참조합니다. 이렇게 하면 요청을 복제하지 않고도 하나의 요청으로 수십 가지 입력 조합을 테스트할 수 있습니다. 예를 들어, 로그인 엔드포인트는 유효한 자격 증명 한 행과 여러 줄의 잘못된 자격 증명으로 호출될 수 있으며, 각 행은 예상되는 상태 코드를 어설션합니다. CSV 및 JSON을 사용한 데이터 기반 API 테스트에 대한 글에서 이 패턴을 자세히 다룹니다. GUI 없이 CI에서 동일한 컬렉션을 실행하려면 Postman은 Newman과 Postman 비교에 설명된 Newman 명령줄 도구를 제공합니다.
Postman이 복잡해지는 지점 및 고려 사항
Postman은 탐색적 테스트 및 중소 규모 스위트에 탁월합니다. 프로젝트가 커짐에 따라 두 가지 문제점이 나타납니다. 첫째, 어설션은 JavaScript로 작성되므로 시각적 접근 방식을 선호하는 비개발자 및 QA 담당자는 학습 곡선이 있습니다. 둘째, Postman은 API 설계, 테스트, 목(mocking) 및 문서를 서로 다른 곳에 보관하므로 테스트 데이터와 API 계약이 일치하지 않을 수 있습니다.
Apidog는 이 두 가지 문제를 모두 해결하는 올인원 API 플랫폼입니다. Postman 컬렉션을 직접 가져올 수 있으므로 마이그레이션이 다시 작성하는 작업이 아닙니다. 어설션은 코드 없이 시각적으로 구축할 수 있으며, 필요할 때는 스크립트도 허용합니다. 설계, 디버깅, 목(mocking), 테스트 및 문서가 단일 정보원을 공유하므로 테스트가 실제 API 사양과 일치하게 유지됩니다. 다른 옵션을 고려하고 있다면, API 테스트를 위한 Postman 대안에 대한 요약본에서 장단점을 파악할 수 있습니다. Apidog를 다운로드하고 기존 컬렉션을 가져와 직접 비교해 볼 수 있습니다.
이 모든 것이 Postman을 버려야 한다는 의미는 아닙니다. 특히 빠른 확인이나 이미 Postman에 투자한 팀에게는 여전히 견고한 선택입니다. 핵심은 각 도구가 어디에 적합한지 아는 것입니다.
자주 묻는 질문
Postman에서 API를 테스트하려면 코드를 작성해야 하나요?
요청을 보내고 응답을 읽는 데는 필요 없습니다. 자동화된 어설션의 경우, 네, 최소한 약간은 필요합니다. Postman의 "테스트(Tests)" 탭은 JavaScript를 실행하고 pm 객체를 사용합니다. 패턴은 간단하며 Postman의 내장 스니펫 패널에서 복사할 수 있지만, 여전히 JavaScript입니다. 코드 없는 시각적 어설션 빌더를 원한다면 Apidog와 같은 전용 플랫폼이 이를 처리합니다.
Postman 컬렉션과 환경의 차이점은 무엇인가요?
컬렉션은 종종 테스트와 함께 그룹화된 요청 집합입니다. 환경은 base_url 또는 auth_token과 같이 이름이 지정된 변수 집합입니다. 컬렉션은 보내는 내용을 담습니다. 환경은 스테이징, 프로덕션 및 로컬 간에 변경되는 값을 담습니다. 하나의 컬렉션을 다른 환경에 연결하여 다른 서버에 대해 동일한 요청을 테스트할 수 있습니다.
CI에서 Postman 테스트를 자동으로 실행하려면 어떻게 해야 하나요?
Postman의 명령줄 러너인 Newman을 사용하세요. 컬렉션과 환경을 내보낸 다음 newman run collection.json -e environment.json을 실행합니다. Newman은 테스트가 실패하면 0이 아닌 코드로 종료하며, 이는 CI 파이프라인이 확인하는 부분입니다. CI/CD에서 API 테스트 자동화 가이드에서 이를 파이프라인에 연결하는 방법을 설명합니다.
Postman은 REST API 외에도 테스트할 수 있나요?
네. 최신 Postman은 일반 HTTP 및 REST 외에도 GraphQL, gRPC, WebSocket 및 SOAP 요청을 지원합니다. "테스트(Tests)" 탭과 어설션은 대부분의 경우 작동하지만, 정확한 요청 설정은 프로토콜마다 다릅니다.
하나의 요청에 몇 개의 어설션이 있어야 하나요?
응답이 올바른지 확인하기에 충분해야 하며, 하나의 변경으로 인해 수십 개의 테스트가 깨질 정도로 많아서는 안 됩니다. 일반적인 기준은 상태 코드, 응답 시간, 그리고 해당 엔드포인트에 중요한 두세 개의 필드입니다. 각 pm.test 블록을 하나의 기대치에 집중시켜 실패 시 무엇이 깨졌는지 정확히 알려주도록 하세요.