Postman 핵심 정리: API 테스트 기본부터 JWT 로그인 자동화, 디버깅까지

[ Postman이란 ]

Postman은 이름 그대로 ‘우체부’ 라는

뜻에서 출발한 도구다.

 

개발 관점에서는 API를 만들고 테스트하는 과정을

한 화면에서 처리할 수 있게 해주는 통합 플랫폼이다.

 

브라우저에서 클릭만으로 확인하기 어려운

요청 스펙(URL, 헤더, 바디 등)과

응답(상태코드, 바디 등)을 ‘증거’로 남기듯

확인할 수 있어서, 프론트가 완성되기 전 단계에서

백엔드 API를 빠르게 검증할 때 특히 유용하다.

 

Postman에서 자주 쓰는 기능 요약

1. HTTP 요청/응답 확인
   GET, POST, PUT, DELETE 등으로
   요청 전송, JSON/XML 응답 확인
2. 변수 관리
   개발/스테이징/운영 환경별 baseUrl,
   token 같은 값을 변수로 관리
3. 컬렉션
   요청을 묶어서 재사용하고 팀과 공유
4. 자동화 스크립트
   응답을 검증하고, 토큰 같은 값을 자동 저장
5. 문서화/공유
   API 사용 예시를 팀에 전달하기 쉬움

---

1. API 테스트가 필요한 이유

백엔드 API는 프론트 화면이 없어도

독립적으로 동작해야 한다.

 

그런데 브라우저는 보통 ‘완성된 화면 흐름’을 기준으로

확인하기 때문에 API 요청 자체를 분해해서 보기 어렵다.

 

API 테스트가 필요한 대표 이유

• 프론트 개발 전에 백엔드 API
  정상 동작을 먼저 검증할 수 있음
• 요청/응답 구조를 정확히 확인 가능
  (Params, Headers, Body, Status Code)
• 에러 상황(400/401/403/500)을 미리 잡아서
  개발 속도와 안정성을 같이 올릴 수 있음

간단 예시 흐름

• 서버에 GET API를 만들었다고 가정
• Postman에서 GET 요청으로
  http://localhost:8080/api/get 호출
• 응답으로 JSON이 내려오는지 확인

응답 예시

{ "hello": "get Hello" }

---

2. Postman 기본 구조

Postman은 크게 아래 4개 단위로 생각하면 된다.

 

구조 한눈에 보기

- Workspace

작업 공간, 프로젝트 단위로 분리

- Collection

요청 묶음, 폴더로 시나리오

(로그인 → 보호 API) 구성 가능

- Request

실제 요청 하나

(메서드, URL, 헤더, 바디 포함)

- Environment

baseUrl, token 같은 변수를 저장하는 공간

(환경별로 분리 가능)

---

3. Postman으로 API 요청 보내기

Postman의 모든 요청은

아래 5요소 조합으로 정리된다.

요청 사양 = URL + Method + Params + Headers + Body

- Method : 상단에서 선택
(GET/POST/PUT/DELETE)

- URL : 상단 주소 입력칸

- Params : Params 탭
필터/검색/페이지 같은 쿼리스트링

- Headers : Headers 탭
인증 Authorization, 데이터 형식 Content-Type

- Body : Body 탭
POST/PUT에서 주로 사용, raw JSON 또는 form-data

 

요청 작성 체크 표(최소 필수 점검)

항목	체크 내용	자주 터지는 실수
Method	GET/POST 혼동 없는지	GET인데 Body 넣으려 함
URL	경로 오타/변수 누락 없는지	baseUrl 착각, 슬래시 누락
Params	필요한 값이 쿼리로 붙는지	page, keyword 누락
Headers	Content-Type, Authorization 정확한지	Content-Type 누락, Bearer 누락
Body	JSON 형식/필수값 맞는지	키 오타, 콤마/중괄호 깨짐

---

4. 인증 API 테스트 실습 흐름(JWT 로그인)

목표는 단순하다.
‘로그인 버튼’을 API 레벨에서 그대로 재현하고,

토큰이 다음 요청에 정상 적용되는지 검증하는 것이다.

 

전체 시나리오 흐름도

[1] POST /api/login (email, password)
↓
[2] 응답 JSON에서 token 확인
↓
[3] token을 Environment 변수로 저장
↓
[4] 보호 API 요청에 Authorization: Bearer {{token}} 적용해서 호출

 

실습 세팅: 재현성 만들기

• Collection으로 로그인 요청과
  보호 API 요청을 묶는다
• Environment에 baseUrl,
  token 변수를 만든다
• 같은 컬렉션을 팀원에게 공유해도
  동일한 테스트를 재현할 수 있다

Environment 변수 예시

• baseUrl: 예) http://localhost:8080
• token: 초기에는 비어 있음(로그인 성공 후 자동 저장)

4-1) 로그인 요청 만들기

요청: POST {{baseUrl}}/api/login

체크리스트

• Method: POST
• URL: {{baseUrl}}/api/login
• Body: raw(JSON)로 email, password
• Headers: Content-Type = application/json
• Authorization: No Auth(로그인 요청에는 토큰이 없다)

Body 예시(표현 편의상 작은따옴표 사용)

{
  'email': 'test@example.com',
  'password': '1234'
}

 

4-2) 로그인 응답 확인

성공 기준

• Status Code: 200
• Response Body에 token 필드가 존재

JWT 기반 인증 구조 정리

• 클라이언트(Postman/브라우저) → 서버(API)
• 성공 시 서버가 token을 JSON으로 반환
• 이후 요청은 Authorization 헤더로 token을 전달

실패 시 상태코드 기준 빠른 분류

코드	의미	가장 먼저 볼 것
400	요청 형식/필수값 문제	Body, Content-Type
401	인증 실패	계정정보, 토큰 존재/만료
403	권한/정책 차단	사용자 권한, 서버 정책
500	서버 내부 예외	서버 로그/스택트레이스

 

4-3) 토큰 자동 저장(Tests 스크립트)

Postman의 Tests는 요청에 대한

응답을 받은 뒤 실행되는 코드다.
로그인 성공 응답에서 token을 꺼내

Environment에 저장하면 다음 요청에서

복붙 없이 재사용할 수 있다.

 

Tests 스크립트 예시

pm.test('login status is 200', () => pm.response.to.have.status(200));

const data = pm.response.json();
pm.environment.set('token', data.token);
pm.environment.set('tokenType', 'Bearer');

결과

• Environment의 token 값이 자동으로 채워짐
• tokenType은 Bearer로 고정해두면
  헤더 구성 실수를 줄일 수 있음

4-4) 보호 API 호출

요청 예시)

GET {{baseUrl}}/api/users/2

 

Authorization 설정 방법 2가지 중 택1

• Authorization 탭: Bearer Token → Token = {{token}}
• Headers 탭: Authorization = {{tokenType}} {{token}}

확인 포인트

• Headers 또는 Console에서
  Authorization 헤더가 실제로 붙었는지 확인
• token이 비어 있으면 Tests 스크립트와
  Environment 활성화 상태부터 점검

---

5. 에러 상황 디버깅 경험 정리

디버깅은 순서를 고정하면 빨라진다.
Status → Body → Headers → Console

디버깅 흐름도(원인 좁히기)

요청 전송
↓
Status Code 확인(분류)
↓
Response Body에서 error/message 확인
↓
Request Headers 점검(Content-Type, Authorization)
↓
Postman Console로 실제 전송값 확인(증거 확보)

케이스 1) 400 Bad Request(요청 형식 문제)

- 증상

Status 400, Response Body에 error/message

- 원인 후보

필수값 누락(email/password)

JSON 형식 깨짐, 키 이름 오타

Content-Type 불일치

- 확인 위치

Body 탭, Headers(Content-Type), Response Body

- 해결

필수값/키/JSON 수정 후 재요청

 

케이스 2) 401 Unauthorized(토큰/Authorization 문제)

- 증상

Status 401

- 원인 후보

Authorization 헤더 없음

Bearer 형식 누락

토큰 만료/변조

- 확인 위치

Authorization 탭 또는 Headers 탭, Console(실제 헤더)

- 해결

Authorization: Bearer {{token}} 형태 고정

Environment에 token 값이 존재하는지 확인

 

케이스 3) token 변수가 안 채워짐(자동화/환경 문제)

- 증상

{{token}}가 빈 값 → 보호 API에서 401

- 원인 후보

Tests에서 잘못된 키로 저장(예: data.accessToken로 착각)

올바른 Environment를 선택하지 않음

- 확인 위치

Environments의 token 값, Tests 스크립트, Console

- 해결

pm.environment.set('token', data.token); 로 키 맞추기

현재 활성 Environment가 맞는지 확인

---

[ Postman 장단점과 주의할 점 ]

장점

• 요청/응답 재현만으로 백엔드 로직을 빠르게 검증 가능
• Status/Body/Headers로 원인 분해가 쉬움
• Environment로 baseUrl, token 관리 → 재현성/협업 향상
• Scripts(Tests, Pre-request)로 인증/반복 테스트 자동화
• Collection 공유로 팀 테스트 표준화 가능

한계 및 현실 차이

• 브라우저와 달라 CORS, 스토리지,
  리다이렉트 이슈 체감이 덜함
• 실제 사용자 흐름(프론트 상태, 동시성)을
  100퍼센트 재현하기는 어려움
• 변수/환경 선택 실수로 헷갈리기 쉬움
• 토큰/키 등 민감정보가 노출될 위험이 있음

사용 시 주의할 점 체크리스트

• 로그인 요청은 No Auth(토큰 없음)
• Authorization은 {{tokenType}} {{token}} 형태로 고정
• 토큰/키는 공유 또는 스크린샷 시 마스킹, 환경 파일 분리
• 디버깅은 Status → Body
  → Headers → Console 순서로 고정
• 컬렉션 공유 시 Environment에는 민감 값 제거