Python API GET 테스트 작성법｜pytest・requests로 상태 코드・응답 검증

Python과 pytest로 API 테스트를 작성할 때 처음으로 구현하는 것이 GET 요청 테스트입니다. pytest와 requests를 사용해서 「상태 코드는 200인가？」「JSON 응답에 필요한 필드가 포함되어 있는가？」를 자동으로 검증하는 방법을 해설합니다.

이 글에서는 기본적인 상태 코드 확인부터 응답 바디의 스키마 검증까지를 실무에서 사용할 수 있는 코드와 함께 소개합니다.

00. API 테스트와 GET 요청의 기본

API 테스트란, 브라우저를 사용하지 않고 HTTP 요청을 직접 전송하여 응답을 검증하는 테스트입니다. GET 요청은 API에서 가장 기본적인 조작으로 「데이터를 가져오는」 역할을 담당합니다.

GET 테스트에서는 주로 다음 3가지를 검증합니다.

💡 포인트：실무에서는 상태 코드뿐만 아니라 응답 내용까지 검증하는 것이 중요합니다. 상태가 200이어도 응답 값이 틀리면 버그입니다.

01. pytest + requests의 API 테스트 환경

아직 환경 구축이 안 된 분은 먼저 설치해주세요.

pip install requests pytest pytest-html

이번 테스트 대상은 무료 목（mock） API JSONPlaceholder 입니다.

GET https://jsonplaceholder.typicode.com/users/1

응답 샘플은 다음과 같습니다.

{
    "id": 1,
    "name": "Leanne Graham",
    "username": "Bret",
    "email": "Sincere@april.biz",
    "phone": "1-770-736-8031 x56442",
    "website": "hildegard.org"
}

💡 포인트：JSONPlaceholder는 데이터 변경・삭제가 실제로는 이루어지지 않는 목 API입니다. 학습용으로 안심하고 사용할 수 있습니다.

02. Python으로 API GET 테스트를 작성하는 방법

상태 코드 검증

가장 기본적인 테스트입니다. 요청을 보내서 200이 반환되는 것을 확인합니다.

import requests

BASE_URL = "https://jsonplaceholder.typicode.com"

def test_get_user_status_code():
    """TC01: 상태 코드가 200이어야 한다"""
    response = requests.get(f"{BASE_URL}/users/1")

    assert response.status_code == 200, \
        f"기댓값: 200, 실제 값: {response.status_code}"

    print(f"\n✅ TC01 PASS | 상태 코드: {response.status_code}")

raise_for_status()로 4xx/5xx를 확실히 검지

실무에서 자주 사용되는 작성법입니다. raise_for_status() 를 추가하는 것만으로 4xx / 5xx 오류가 반환됐을 때 자동으로 예외를 발생시켜 테스트를 실패시킬 수 있습니다.

def test_get_user_raise_for_status():
    """TC02: 4xx/5xx 오류 시 예외가 발생해야 한다"""
    response = requests.get(f"{BASE_URL}/users/1")

    # 4xx/5xx 때 자동으로 HTTPError 발생
    response.raise_for_status()

    assert response.status_code == 200
    print(f"\n✅ TC02 PASS | raise_for_status() 정상 통과")

💡 포인트：response.raise_for_status() 는 실무에서 필수 1행입니다. assert로 상태 코드를 체크하기 전에 넣어두면 예기치 못한 오류 응답을 확실히 검지할 수 있습니다.

헤더 검증

응답의 Content-Type이 올바른지도 확인합니다. JSON을 기대하고 있는데 HTML이 반환되는 경우를 검지할 수 있습니다.

def test_get_user_header():
    """TC03: Content-Type이 JSON이어야 한다"""
    response = requests.get(f"{BASE_URL}/users/1")

    response.raise_for_status()

    content_type = response.headers.get("Content-Type", "")
    assert "application/json" in content_type, \
        f"예상 밖의 Content-Type: {content_type}"

    print(f"\n✅ TC03 PASS | Content-Type: {content_type}")

💡 포인트：실제 Content-Type 헤더는 application/json; charset=utf-8 형태로 반환됩니다. == 완전 일치가 아닌 in 으로 부분 일치를 사용하세요.

응답 JSON 검증

상태 코드뿐만 아니라 응답 값이 올바른지도 확인합니다.

def test_get_user_response_body():
    """TC04: 응답 바디의 값이 올바르다"""
    response = requests.get(f"{BASE_URL}/users/1")

    response.raise_for_status()
    body = response.json()

    assert body["id"] == 1,                      f"id 불일치: {body['id']}"
    assert body["name"] == "Leanne Graham",      f"name 불일치: {body['name']}"
    assert body["email"] == "Sincere@april.biz", f"email 불일치: {body['email']}"

    print(f"\n✅ TC04 PASS | 사용자 이름: {body['name']}")

필수 필드 존재 확인

필요한 필드가 전부 포함되어 있는지 체크합니다.

def test_get_user_fields_exist():
    """TC05: 필수 필드가 존재해야 한다"""
    response = requests.get(f"{BASE_URL}/users/1")
    response.raise_for_status()
    body = response.json()

    required_fields = ["id", "name", "username", "email", "phone", "website"]
    for field in required_fields:
        assert field in body, f"필수 필드 '{field}' 가 존재하지 않습니다"

    print(f"\n✅ TC05 PASS | 모든 필수 필드 확인 완료")

💡 포인트：필드를 리스트로 관리하면 필수 항목이 늘어나도 코드 변경이 최소화됩니다. 실무에서 자주 사용되는 작성법입니다.

03. API 테스트 스키마（타입）검증

응답 값뿐만 아니라 타입（int/str/dict）이 올바른지도 테스트합니다. 타입이 변하면 프론트엔드가 망가질 수 있기 때문에 실무에서 중요한 검증입니다.

def test_get_user_schema():
    """TC06: 응답 스키마（타입）가 올바르다"""
    response = requests.get(f"{BASE_URL}/users/1")
    response.raise_for_status()
    body = response.json()

    assert isinstance(body["id"],       int),  f"id는 int여야 함: {type(body['id'])}"
    assert isinstance(body["name"],     str),  f"name은 str여야 함: {type(body['name'])}"
    assert isinstance(body["username"], str),  f"username은 str여야 함: {type(body['username'])}"
    assert isinstance(body["email"],    str),  f"email은 str여야 함: {type(body['email'])}"
    assert isinstance(body["address"],  dict), f"address는 dict여야 함: {type(body['address'])}"
    assert isinstance(body["company"],  dict), f"company는 dict여야 함: {type(body['company'])}"

    print(f"\n✅ TC06 PASS | 스키마 검증 완료")

💡 포인트：isinstance() 를 사용하면 타입 체크를 간단하게 할 수 있습니다. API 응답 타입이 변경됐을 때 즉시 검지할 수 있어 실무에서는 필수 검증입니다.

04. API 테스트 이상계 패턴

존재하지 않는 리소스에 접근（404 확인）

def test_get_nonexistent_user():
    """TC07: 존재하지 않는 사용자에 접근하면 404가 반환된다"""
    response = requests.get(f"{BASE_URL}/users/99999")

    assert response.status_code == 404, \
        f"존재하지 않는 리소스의 기댓값은 404: {response.status_code}"

    print(f"\n✅ TC07 PASS | 404 정상 확인: {response.status_code}")

목록 취득 및 건수 확인

def test_get_all_users():
    """TC08: 전체 사용자 목록이 10건 취득된다"""
    response = requests.get(f"{BASE_URL}/users")
    response.raise_for_status()
    body = response.json()

    assert isinstance(body, list), "응답은 리스트 형식이어야 한다"
    assert len(body) == 10, f"사용자 수는 10건이 기댓값: {len(body)}건"

    print(f"\n✅ TC08 PASS | 사용자 목록 취득 성공: {len(body)}건")

⚠️ 주의：이상계 테스트는 정상계와 마찬가지로 중요합니다. 존재하지 않는 리소스에 대해 올바르게 404가 반환되는지 확인함으로써 API의 에러 핸들링이 올바르게 구현되어 있는지 검증할 수 있습니다.

05. API 테스트 응답 시간 검증

성능 관점에서 응답이 일정 시간 내에 반환되는지도 확인합시다.

import time

def test_get_user_response_time():
    """TC09: 응답 시간이 2000ms 이내여야 한다"""
    start = time.time()
    response = requests.get(f"{BASE_URL}/users/1")
    elapsed_ms = (time.time() - start) * 1000

    assert response.status_code == 200
    assert elapsed_ms < 2000, \
        f"응답이 너무 느립니다: {elapsed_ms:.0f}ms（상한: 2000ms）"

    print(f"\n✅ TC09 PASS | 응답 시간: {elapsed_ms:.0f}ms")

💡 포인트：응답 시간의 임계값은 시스템 요건에 맞게 조정하세요. CI/CD에 통합하면 성능 저하를 자동으로 검지할 수 있습니다.

06. GET 테스트 전체 코드

"""
GET API Test
Target: JSONPlaceholder (https://jsonplaceholder.typicode.com)
Framework: Python + requests + pytest
"""
import time
import requests

BASE_URL = "https://jsonplaceholder.typicode.com"


def test_get_user_status_code():
    """TC01: 상태 코드가 200이어야 한다"""
    response = requests.get(f"{BASE_URL}/users/1")
    assert response.status_code == 200, \
        f"기댓값: 200, 실제 값: {response.status_code}"
    print(f"\n✅ TC01 PASS | status: {response.status_code}")


def test_get_user_raise_for_status():
    """TC02: 4xx/5xx 오류 시 예외가 발생해야 한다"""
    response = requests.get(f"{BASE_URL}/users/1")
    response.raise_for_status()
    assert response.status_code == 200
    print(f"\n✅ TC02 PASS | raise_for_status() 정상 통과")


def test_get_user_header():
    """TC03: Content-Type이 JSON이어야 한다"""
    response = requests.get(f"{BASE_URL}/users/1")
    response.raise_for_status()
    content_type = response.headers.get("Content-Type", "")
    assert "application/json" in content_type, \
        f"예상 밖의 Content-Type: {content_type}"
    print(f"\n✅ TC03 PASS | Content-Type: {content_type}")


def test_get_user_response_body():
    """TC04: 응답 바디의 값이 올바르다"""
    response = requests.get(f"{BASE_URL}/users/1")
    response.raise_for_status()
    body = response.json()
    assert body["id"] == 1
    assert body["name"] == "Leanne Graham"
    assert body["email"] == "Sincere@april.biz"
    print(f"\n✅ TC04 PASS | name: {body['name']}")


def test_get_user_fields_exist():
    """TC05: 필수 필드가 존재해야 한다"""
    response = requests.get(f"{BASE_URL}/users/1")
    response.raise_for_status()
    body = response.json()
    for field in ["id", "name", "username", "email", "phone", "website"]:
        assert field in body, f"필수 필드 '{field}' 가 존재하지 않습니다"
    print(f"\n✅ TC05 PASS | 모든 필수 필드 확인 완료")


def test_get_user_schema():
    """TC06: 스키마（타입）가 올바르다"""
    response = requests.get(f"{BASE_URL}/users/1")
    response.raise_for_status()
    body = response.json()
    assert isinstance(body["id"],      int)
    assert isinstance(body["name"],    str)
    assert isinstance(body["email"],   str)
    assert isinstance(body["address"], dict)
    assert isinstance(body["company"], dict)
    print(f"\n✅ TC06 PASS | 스키마 검증 완료")


def test_get_nonexistent_user():
    """TC07: 존재하지 않는 사용자는 404를 반환해야 한다"""
    response = requests.get(f"{BASE_URL}/users/99999")
    assert response.status_code == 404
    print(f"\n✅ TC07 PASS | 404 확인: {response.status_code}")


def test_get_all_users():
    """TC08: 전체 사용자 목록이 10건 취득된다"""
    response = requests.get(f"{BASE_URL}/users")
    response.raise_for_status()
    body = response.json()
    assert isinstance(body, list)
    assert len(body) == 10
    print(f"\n✅ TC08 PASS | 사용자 수: {len(body)}건")


def test_get_user_response_time():
    """TC09: 응답 시간이 2000ms 이내여야 한다"""
    start = time.time()
    response = requests.get(f"{BASE_URL}/users/1")
    elapsed_ms = (time.time() - start) * 1000
    assert response.status_code == 200
    assert elapsed_ms < 2000, f"{elapsed_ms:.0f}ms（상한: 2000ms）"
    print(f"\n✅ TC09 PASS | 응답 시간: {elapsed_ms:.0f}ms")

실행 커맨드

pytest test_get_api.py -v -s

실행 결과 샘플

test_get_api.py::test_get_user_status_code      PASSED
test_get_api.py::test_get_user_raise_for_status PASSED
test_get_api.py::test_get_user_header           PASSED
test_get_api.py::test_get_user_response_body    PASSED
test_get_api.py::test_get_user_fields_exist     PASSED
test_get_api.py::test_get_user_schema           PASSED
test_get_api.py::test_get_nonexistent_user      PASSED
test_get_api.py::test_get_all_users             PASSED
test_get_api.py::test_get_user_response_time    PASSED

9 passed in 3.45s ✅

07. 자주 겪는 문제 & 해결법

구현 중 실제로 겪었던 문제들을 정리했습니다. 같은 곳에서 막히는 분들께 도움이 되면 좋겠습니다.

① response.json()에서 KeyError가 발생한다

JSON에서 값을 꺼낼 때 키 이름 오타나 대소문자 차이로 KeyError 가 발생했습니다.

# ❌ 키 이름 오타
assert body["Name"] == "Leanne Graham"  # KeyError！（N이 대문자）

# ✅ 먼저 print()로 키 이름 확인
print(body.keys())
# dict_keys(['id', 'name', 'username', 'email', ...])

# ✅ get()을 사용하면 KeyError를 방지할 수 있다
name = body.get("name", "")  # 키가 없으면 빈 문자열 반환

💡 포인트：처음 테스트하는 API는 반드시 print(response.json()) 로 응답 구조를 확인하고 나서 테스트 코드를 작성합시다.

② 상태 코드가 200인데 테스트가 실패한다

상태 코드가 200인데 assert가 실패하는 경우가 있었습니다. 원인은 응답 바디가 빈 JSON이나 예상 외의 구조로 반환되고 있었기 때문입니다.

# ❌ 상태 코드만 확인하고 안심해버린다
assert response.status_code == 200  # 통과해도 내용이 비어있을 가능성

# ✅ 응답 바디도 함께 확인한다
assert response.status_code == 200
assert response.json() is not None
assert len(response.json()) > 0

💡 포인트：「200이 반환됐다 = 성공」이 아닙니다. 응답 내용까지 검증하는 것이 API 테스트의 본질입니다.

③ isinstance()로 중첩된 JSON 타입 체크에 실패한다

중첩된 JSON 필드（address.city 등）를 검증하려고 했을 때 올바르게 접근하지 못해 오류가 발생했습니다.

# ❌ 중첩된 필드에 직접 접근하려고 해서 실패
assert isinstance(body["address.city"], str)  # KeyError！

# ✅ 올바른 중첩 접근 방법
assert isinstance(body["address"]["city"], str)
assert isinstance(body["address"]["zipcode"], str)

💡 포인트：중첩된 JSON은 body["address"]["city"] 처럼 단계적으로 접근합니다. 먼저 print(body["address"]) 로 구조를 확인하고 나서 작성하면 안심입니다.

④ 응답 시간이 환경에 따라 들쑥날쑥하다

로컬에서는 1000ms 이내인데 CI 환경에서는 2000ms를 초과해서 테스트가 실패하는 경우가 있었습니다.

# ❌ 너무 엄격한 임계값
assert elapsed_ms < 500  # CI에서는 실패할 수 있다

# ✅ 환경을 고려한 여유 있는 임계값으로 설정
assert elapsed_ms < 3000  # 3초 이내면 충분

⚠️ 주의：응답 시간은 네트워크 환경과 서버 부하에 따라 달라집니다. 여유 있는 임계값을 설정해두세요.

⑤ 목록 취득에서 데이터 건수가 바뀌어 테스트가 깨진다

테스트 환경의 데이터가 바뀌면 건수도 바뀌어 테스트가 깨졌습니다. 실제 프로젝트에서는 고정값보다 조건 검증이 더 견고합니다.

# ❌ 건수를 고정값으로 검증하면 깨지기 쉽다
assert len(body) == 10  # 데이터가 증감하면 실패

# ✅ 건수보다 「1건 이상 존재할 것」을 검증하는 편이 견고하다
assert len(body) >= 1, "사용자가 1건도 존재하지 않습니다"
assert isinstance(body, list), "응답은 리스트 형식이어야 한다"

💡 포인트：JSONPlaceholder 같은 고정 목 API는 고정값도 OK입니다. 실제 프로젝트에서는 데이터가 바뀌어도 깨지지 않는 설계를 의식합시다.

08. 자주 묻는 질문（FAQ）

Q. API 테스트의 GET 테스트에서 최소한 확인해야 할 것은 무엇인가요？
A. 최소한 「상태 코드가 200인 것」과 「필수 필드가 존재하는 것」 2가지입니다. 여유가 있다면 타입 체크・값 검증・응답 시간도 추가하면 실무 수준의 API 테스트가 됩니다.

Q. requests.get()과 requests.head()의 차이는 무엇인가요？
A. get() 은 응답 바디도 취득합니다. head() 는 헤더 정보만 취득하고 바디를 취득하지 않기 때문에 빠릅니다. 상태 코드만 확인하고 싶은 경우는 head() 가 효율적이지만, 서버에 따라서는 head() 를 거부하는 경우도 있습니다.

Q. assert와 pytest.raises는 어떻게 구분해서 사용하나요？
A. 정상계 응답 검증에는 assert 를 사용합니다. 예외（오류）가 발생하는 것을 확인하고 싶은 경우는 pytest.raises 를 사용합니다. API 테스트에서는 기본적으로 assert 로 충분합니다.

Q. GET 테스트의 테스트 케이스는 얼마나 작성하면 좋나요？
A. 최소한 「정상계 1건・이상계 1건」부터 시작합시다. 실무에서는 「상태 확인・바디 검증・스키마 검증・404 확인・응답 시간」의 5〜7건이 기준입니다. 이번 TC01〜TC09가 그대로 실무 표준 패턴이 됩니다.

Q. JSONPlaceholder 외에 API 테스트용 사이트가 있나요？
A. 예. 인증 플로우 테스트에는 Restful Booker, 더 본격적인 API에는 reqres.in 이나 httpbin.org 를 사용할 수 있습니다. 포트폴리오용으로는 JSONPlaceholder（CRUD）와 Restful Booker（인증）의 조합이 추천입니다.

09. 정리

Python으로 API GET 테스트를 구현하는 경우, pytest와 requests를 사용해서 상태 코드・응답 바디・스키마의 3가지를 검증하는 것이 실무의 기본입니다. 간단한 코드로 망라적인 테스트를 작성할 수 있습니다.

이 글에서는 pytest와 requests를 사용한 API GET 테스트 구현 방법을 해설했습니다.

다음 글에서는 POST 요청의 API 테스트（데이터 생성・유효성 검사 확인）를 해설합니다.