DEV Community

Cover image for 포스트맨으로 API 테스트하는 방법: 실전 가이드
Rihpig
Rihpig

Posted on • Originally published at apidog.com

포스트맨으로 API 테스트하는 방법: 실전 가이드

Postman은 HTTP 요청을 보내고 API 동작을 확인하는 데 널리 사용되는 도구입니다. 빠른 GET 요청 확인부터 CI에서 실행하는 자동화 테스트까지 처리할 수 있어, API를 만들거나 사용하는 개발자라면 자주 접하게 됩니다.

오늘 Apidog를 사용해 보세요

이 가이드에서는 Postman으로 API를 테스트하는 실무 흐름을 다룹니다. 요청을 보내고, 응답을 확인하고, Tests에서 어설션을 작성하고, 환경 변수를 사용해 스테이징/프로덕션을 전환하고, Collection Runner로 전체 테스트를 실행하는 방법까지 단계별로 정리합니다. 예제는 공용 API를 사용하므로 별도 서버 설정 없이 따라 할 수 있습니다.

Postman 설정 및 첫 번째 요청 보내기

공식 사이트에서 Postman 데스크톱 앱을 설치합니다. 계정 없이도 로컬에서 사용할 수 있지만, 로그인하면 컬렉션을 여러 장치에서 동기화할 수 있습니다.

앱을 연 뒤 다음 순서로 첫 요청을 만듭니다.

  1. New 클릭
  2. HTTP Request 선택
  3. 메서드에서 GET 선택
  4. URL 입력
  5. Send 클릭

예제로 JSONPlaceholder API를 호출합니다.

GET https://jsonplaceholder.typicode.com/users/1
Enter fullscreen mode Exit fullscreen mode

응답 패널에서 다음 항목을 확인합니다.

  • 상태 코드: 200 OK
  • 응답 시간
  • 응답 크기
  • JSON 응답 본문

본문은 Pretty, Raw, Preview 보기로 전환할 수 있습니다.

POST 요청을 테스트하려면 메서드를 POST로 바꾸고 Body 탭에서 다음을 설정합니다.

  1. raw 선택
  2. 형식 드롭다운에서 JSON 선택
  3. JSON 페이로드 입력 
{
  "name": "Maria Chen",
  "email": "maria.chen@example.com"
}
Enter fullscreen mode Exit fullscreen mode

JSON 형식을 선택하면 Postman이 보통 다음 헤더를 자동으로 추가합니다.

Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

추가 인증이 필요하다면 Headers 탭에서 다음과 같이 넣을 수 있습니다.

Authorization: Bearer <token>
Enter fullscreen mode Exit fullscreen mode

예상해야 할 상태 코드가 헷갈린다면 REST API가 사용해야 하는 HTTP 상태 코드를 참고하세요.

요청을 컬렉션으로 구성하기

단일 요청은 빠른 확인에 적합하지만, 실제 API 테스트는 보통 여러 요청으로 구성됩니다.

예를 들어 사용자 API라면 다음 흐름이 필요할 수 있습니다.

  1. 사용자 생성
  2. 사용자 조회
  3. 사용자 수정
  4. 사용자 삭제

Postman에서는 이런 요청들을 Collection으로 묶습니다.

컬렉션을 만드는 방법은 다음과 같습니다.

  1. 사이드바에서 Collections 클릭
  2. + 클릭
  3. 컬렉션 이름 입력 예: 사용자 API 스모크 테스트
  4. 각 요청을 Ctrl/Cmd + S로 컬렉션에 저장
  5. 요청 이름을 명확하게 지정 예: 사용자 단건 조회, 사용자 생성

컬렉션 내부에는 폴더를 만들 수 있습니다.

예시 구조:

사용자 API 스모크 테스트
├── Auth
│   └── 로그인
├── Users
│   ├── 사용자 생성
│   ├── 사용자 조회
│   ├── 사용자 수정
│   └── 사용자 삭제
Enter fullscreen mode Exit fullscreen mode

컬렉션은 공유 단위이기도 합니다. JSON 파일로 내보내거나, 클라우드에 동기화한 뒤 팀원과 링크로 공유할 수 있습니다.

또한 컬렉션 또는 폴더 수준에서 스크립트를 설정할 수 있습니다.

  • Pre-request Script: 요청 실행 전에 동작
  • Tests: 응답 수신 후 동작

예를 들어 컬렉션 수준의 pre-request script는 모든 요청 전에 실행되므로 토큰 갱신, 타임스탬프 생성 등에 사용할 수 있습니다. 컬렉션 수준 테스트는 모든 요청 뒤에 실행되므로 공통 응답 시간 검증 같은 작업에 적합합니다.

Tests 탭에 어설션 작성하기

요청을 보내는 것만으로는 매번 사람이 응답을 확인해야 합니다. 자동화된 테스트를 만들려면 Tests 또는 최신 UI의 Scripts 영역에 JavaScript 어설션을 작성합니다.

Postman은 테스트 코드에서 pm 객체를 제공합니다. 기본 패턴은 다음과 같습니다.

pm.test("테스트 이름", function () {
    // assertion
});
Enter fullscreen mode Exit fullscreen mode

자주 사용하는 어설션 예시는 다음과 같습니다.

// 상태 코드 확인
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

// 응답 시간 확인
pm.test("Response is under 500ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// JSON 본문의 필드 확인
pm.test("User has the expected email", function () {
    const body = pm.response.json();
    pm.expect(body.email).to.eql("maria.chen@example.com");
});

// 응답 헤더 확인
pm.test("Content-Type is JSON", function () {
    pm.expect(pm.response.headers.get("Content-Type"))
      .to.include("application/json");
});
Enter fullscreen mode Exit fullscreen mode

어설션 문법은 Chai 스타일을 따릅니다. 따라서 pm.expect에서 다음과 같은 표현을 사용할 수 있습니다.

pm.expect(value).to.eql("expected");
pm.expect(value).to.include("json");
pm.expect(value).to.be.above(0);
pm.expect(value).to.be.below(500);
Enter fullscreen mode Exit fullscreen mode

Send를 클릭하면 Test Results 탭에서 각 테스트의 성공/실패를 확인할 수 있습니다.

테스트를 작성할 때는 다음 기준을 적용하세요.

  • pm.test 이름은 엔드포인트가 아니라 검증하려는 동작 중심으로 작성합니다.
  • 상태 코드, 응답 구조, 클라이언트가 의존하는 필드를 우선 검증합니다.
  • 서버 생성 타임스탬프처럼 불안정한 값에 과도하게 의존하지 않습니다.
  • 하나의 테스트 블록은 하나의 기대값에 집중합니다.

예를 들어 좋지 않은 이름은 다음과 같습니다.

pm.test("GET /users/1", function () {
    pm.response.to.have.status(200);
});
Enter fullscreen mode Exit fullscreen mode

더 나은 이름은 다음과 같습니다.

pm.test("사용자 조회 요청은 200을 반환한다", function () {
    pm.response.to.have.status(200);
});
Enter fullscreen mode Exit fullscreen mode

Postman 편집기 옆의 Snippets 패널을 사용하면 자주 쓰는 어설션 코드를 빠르게 삽입할 수 있습니다. 어설션 설계가 더 필요하다면 API 어설션과 이를 잘 작성하는 방법을 참고하세요. 테스트 케이스 구성 관점에서는 API 테스트 케이스 예제도 함께 볼 만합니다.

환경 및 변수 사용하기

요청 URL에 다음 값을 직접 반복해서 쓰면 환경 전환이 어려워집니다.

https://api.staging.example.com
Enter fullscreen mode Exit fullscreen mode

Postman의 Environment를 사용하면 이 문제를 해결할 수 있습니다. 환경은 이름이 지정된 변수 집합입니다.

예를 들어 Staging 환경을 만들고 다음 변수를 추가합니다.

base_url = https://jsonplaceholder.typicode.com
Enter fullscreen mode Exit fullscreen mode

요청에서는 이중 중괄호로 변수를 참조합니다.

GET {{base_url}}/users/1
Enter fullscreen mode Exit fullscreen mode

이제 오른쪽 상단 환경 드롭다운에서 Staging, Production, Local 등을 바꾸면 같은 컬렉션을 다른 서버에 대해 실행할 수 있습니다.

변수는 요청 간 데이터 전달에도 사용할 수 있습니다. 예를 들어 로그인 응답에서 토큰을 저장하려면 Tests에 다음 코드를 작성합니다.

pm.test("Save the auth token", function () {
    const token = pm.response.json().token;
    pm.environment.set("auth_token", token);
});
Enter fullscreen mode Exit fullscreen mode

이후 요청에서는 헤더에 다음과 같이 사용할 수 있습니다.

Authorization: Bearer {{auth_token}}
Enter fullscreen mode Exit fullscreen mode

Postman에서 자주 쓰는 변수 스코프는 다음과 같습니다.

스코프 용도
Environment variables 스테이징, 프로덕션 등 환경별로 달라지는 값
Collection variables 특정 컬렉션에서 공통으로 쓰는 값
Global variables 모든 컬렉션에서 쓰는 전역 값
Local variables 한 번의 실행 동안만 필요한 임시 값

실무에서는 보통 다음처럼 나누면 관리하기 쉽습니다.

Environment variable:
- base_url
- auth_token

Collection variable:
- api_version
- default_timeout
Enter fullscreen mode Exit fullscreen mode

Collection Runner로 전체 컬렉션 실행하기

요청마다 Send를 누르는 방식은 작은 테스트에는 괜찮지만, 회귀 테스트에는 적합하지 않습니다. Collection Runner를 사용하면 컬렉션의 모든 요청을 순서대로 실행하고 테스트 결과를 한 번에 볼 수 있습니다.

실행 방법은 다음과 같습니다.

  1. 컬렉션 열기
  2. Run 클릭 또는 세 점 메뉴에서 Run collection 선택
  3. 실행할 요청 목록 확인
  4. Environment 선택
  5. 반복 횟수 설정
  6. 필요하면 CSV 또는 JSON 데이터 파일 첨부
  7. Run 클릭

Runner는 컬렉션 안의 요청을 위에서 아래로 실행합니다. 따라서 순서가 중요합니다.

예를 들어 인증이 필요한 API라면 다음 순서로 구성합니다.

1. 로그인
2. 사용자 생성
3. 사용자 조회
4. 사용자 수정
5. 사용자 삭제
Enter fullscreen mode Exit fullscreen mode

로그인 요청에서 auth_token을 저장하고, 이후 요청들이 같은 토큰을 사용하도록 만들 수 있습니다.

const token = pm.response.json().token;
pm.environment.set("auth_token", token);
Enter fullscreen mode Exit fullscreen mode

결과 화면에서는 각 요청의 모든 어설션에 대해 성공/실패가 표시됩니다. 배포 직후 Runner를 실행하면 API의 핵심 흐름이 여전히 정상 동작하는지 빠르게 확인할 수 있습니다.

데이터 기반 테스트 실행하기

Collection Runner에는 CSV 또는 JSON 파일을 연결할 수 있습니다. 각 행은 하나의 반복 실행이 되고, 각 열은 변수로 사용할 수 있습니다.

예를 들어 로그인 테스트용 CSV는 다음과 같습니다.

username,password,expected_status
valid@example.com,correct-password,200
invalid@example.com,wrong-password,401
empty@example.com,,400
Enter fullscreen mode Exit fullscreen mode

요청 본문에서는 변수를 이렇게 참조합니다.

{
  "username": "{{username}}",
  "password": "{{password}}"
}
Enter fullscreen mode Exit fullscreen mode

Tests에서는 행별 예상 상태 코드를 검증할 수 있습니다.

pm.test("응답 상태 코드는 데이터 파일의 expected_status와 일치한다", function () {
    pm.response.to.have.status(Number(pm.iterationData.get("expected_status")));
});
Enter fullscreen mode Exit fullscreen mode

이 패턴을 사용하면 같은 요청을 복제하지 않고도 여러 입력 조합을 테스트할 수 있습니다. 더 자세한 내용은 CSV 및 JSON을 사용한 데이터 기반 API 테스트를 참고하세요.

GUI 없이 CI에서 같은 컬렉션을 실행하려면 Newman을 사용할 수 있습니다. Newman과 Postman의 차이는 Newman과 Postman 비교에 정리되어 있습니다.

CI에서 Postman 테스트 실행하기

Postman 컬렉션을 CI 파이프라인에서 실행하려면 Newman을 사용합니다.

먼저 Newman을 설치합니다.

npm install -g newman
Enter fullscreen mode Exit fullscreen mode

Postman에서 컬렉션과 환경을 JSON으로 내보낸 뒤 다음 명령을 실행합니다.

newman run collection.json -e environment.json
Enter fullscreen mode Exit fullscreen mode

테스트가 실패하면 Newman은 0이 아닌 exit code를 반환합니다. CI는 이 값을 보고 빌드를 실패 처리할 수 있습니다.

예를 들어 GitHub Actions에서는 다음처럼 사용할 수 있습니다.

name: API Tests

on:
  push:
    branches:
      - main

jobs:
  postman-tests:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

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

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

CI/CD에 연결하는 방법은 CI/CD에서 API 테스트 자동화 가이드도 참고할 수 있습니다.

Postman이 복잡해지는 지점

Postman은 탐색적 테스트와 중소 규모 테스트 스위트에 적합합니다. 하지만 프로젝트가 커지면 다음 문제가 생길 수 있습니다.

첫째, 자동화 어설션은 JavaScript로 작성해야 합니다. 개발자에게는 자연스럽지만, 비개발자 QA나 시각적 테스트 구성을 선호하는 팀에는 진입 장벽이 될 수 있습니다.

둘째, API 설계, 테스트, 목(mocking), 문서가 분리되어 관리되면 테스트와 API 계약이 어긋날 수 있습니다. 스펙은 바뀌었는데 테스트는 오래된 응답을 기준으로 검증하는 상황이 생길 수 있습니다.

Apidog는 이런 문제를 줄이기 위한 올인원 API 플랫폼입니다. Postman 컬렉션을 가져올 수 있고, 코드 없는 시각적 어설션을 구성할 수 있으며, 필요한 경우 스크립트도 사용할 수 있습니다. 설계, 디버깅, 목(mocking), 테스트, 문서를 하나의 정보원으로 관리할 수 있어 테스트와 API 사양을 맞추기 쉽습니다.

다른 도구를 비교하고 있다면 API 테스트를 위한 Postman 대안을 참고하세요. 직접 비교하려면 Apidog를 다운로드하고 기존 컬렉션을 가져와 테스트해 볼 수 있습니다.

물론 Postman을 반드시 버려야 한다는 뜻은 아닙니다. 빠른 확인, 탐색적 테스트, 이미 Postman에 익숙한 팀에는 여전히 좋은 선택입니다. 중요한 것은 테스트 규모와 팀의 작업 방식에 맞는 도구를 선택하는 것입니다.

자주 묻는 질문

Postman에서 API를 테스트하려면 코드를 작성해야 하나요?

요청을 보내고 응답을 확인하는 데는 코드가 필요하지 않습니다. 하지만 자동화된 어설션을 만들려면 JavaScript를 작성해야 합니다. Postman의 Tests 영역은 pm 객체를 사용하는 JavaScript 코드를 실행합니다. 기본 패턴은 단순하고 Snippets에서 복사할 수 있지만, 코드 없는 시각적 어설션을 원한다면 Apidog 같은 플랫폼을 고려할 수 있습니다.

Postman 컬렉션과 환경의 차이는 무엇인가요?

컬렉션은 요청과 테스트를 묶은 단위입니다. 환경은 base_url, auth_token처럼 실행 대상에 따라 달라지는 변수 집합입니다. 하나의 컬렉션을 여러 환경에 연결하면 같은 요청을 스테이징, 프로덕션, 로컬 서버에 대해 반복 실행할 수 있습니다.

CI에서 Postman 테스트를 자동으로 실행하려면 어떻게 해야 하나요?

Newman을 사용합니다. 컬렉션과 환경을 JSON으로 내보낸 뒤 다음 명령을 실행합니다.

newman run collection.json -e environment.json
Enter fullscreen mode Exit fullscreen mode

테스트가 실패하면 Newman이 0이 아닌 종료 코드를 반환하므로 CI 파이프라인에서 실패로 처리할 수 있습니다.

Postman은 REST API 외에도 테스트할 수 있나요?

네. Postman은 일반 HTTP/REST 외에도 GraphQL, gRPC, WebSocket, SOAP 요청을 지원합니다. Tests 영역과 어설션은 대부분의 경우 사용할 수 있지만, 요청 설정 방식은 프로토콜마다 다릅니다.

하나의 요청에는 몇 개의 어설션이 적절한가요?

응답이 올바른지 판단하기에 충분한 정도가 좋습니다. 일반적으로는 다음 항목을 우선 검증합니다.

  • 상태 코드
  • 응답 시간
  • 응답 본문의 핵심 필드 2~3개
  • 필요한 경우 응답 헤더

각 pm.test 블록은 하나의 기대값에 집중시키는 것이 좋습니다. 그래야 실패했을 때 무엇이 깨졌는지 바로 알 수 있습니다.

Top comments (0)