🧪 FastAPI 앱 테스트 - Pytest로 안전한 코드 만들기 - nojamlog (life is boring but let's find fun!)

Table of Contents

🕒 약 2분 읽는 데 소요됩니다

백엔드 개발에서 테스트는 단순한 선택이 아닌 생존이다. 버그를 줄이고, 전체 서비스의 안정성과 신뢰성을 확보할 수 있게 도와주는 중요한 도구다. 특히 FastAPI는 테스트 친화적인 프레임워크로, 손쉽게 테스트 코드를 작성하고 자동화할 수 있도록 다양한 기능을 제공한다. 이 글에서는 Pytest를 중심으로 FastAPI 애플리케이션의 테스트를 어떻게 작성하고 실행할 수 있는지, 그리고 이를 통해 어떤 이점을 얻을 수 있는지를 Windows 환경 기준으로 정리해보자.

🧰 테스트 환경 구축하기

FastAPI에서는 테스트를 위한 두 가지 도구를 활용한다. 하나는 pytest, 다른 하나는 FastAPI에서 제공하는 TestClient이다. 다음 명령어를 통해 필요한 패키지를 설치하자.

pip install pytest httpx

pytest: Python에서 가장 널리 쓰이는 테스트 프레임워크이다.
httpx: TestClient가 내부적으로 의존하는 비동기 HTTP 클라이언트이다.

설치가 완료되면 테스트를 위한 준비는 끝이다. 이제 실제 코드를 테스트해보자.

🧪 테스트할 기본 API 만들기

아래는 예제로 사용할 FastAPI 애플리케이션이다. main.py라는 이름의 파일로 생성한다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

이제 이 API의 기능을 pytest로 테스트해볼 것이다.

🧪 TestClient로 API 테스트하기

FastAPI는 Starlette 기반으로 만들어졌기 때문에, 자체적으로 TestClient를 제공한다. 이 객체를 활용하면 별도로 서버를 띄우지 않고도 API 요청을 흉내낼 수 있다. 아래는 가장 기본적인 테스트 코드이다. test_main.py 파일을 생성하여 작성한다.

from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_read_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello World"}

TestClient(app): 애플리케이션 인스턴스를 인자로 넘겨준다.
client.get("/"): 실제 GET 요청을 보내는 것처럼 행동한다.
assert: 응답이 기대한 형태인지 검증한다.

🔍 경로 매개변수 및 쿼리 테스트

다음은 경로 매개변수와 쿼리 파라미터를 테스트하는 예시이다.

def test_read_item():
    response = client.get("/items/42?q=fastapi")
    assert response.status_code == 200
    assert response.json() == {"item_id": 42, "q": "fastapi"}

매개변수가 제대로 바인딩되는지 확인할 수 있으며, 쿼리 문자열도 함께 테스트가 가능하다.

✉️ POST 요청 테스트

POST 요청에서는 json= 파라미터를 활용하여 데이터 바디를 함께 보낼 수 있다. 아래는 POST API와 이에 대한 테스트 예시이다.

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
def create_item(item: Item):
    return {"name": item.name, "price": item.price}

이제 해당 API에 대한 테스트를 작성해보자.

def test_create_item():
    response = client.post("/items/", json={"name": "Keyboard", "price": 49.99})
    assert response.status_code == 200
    assert response.json() == {"name": "Keyboard", "price": 49.99}

FastAPI는 요청 본문을 자동으로 Pydantic 모델로 파싱하고 검증하기 때문에 테스트 역시 직관적으로 작성할 수 있다.

🧵 비동기 함수 테스트

FastAPI는 비동기를 지원하므로 async def로 작성된 엔드포인트도 많다. 다행히도 TestClient는 이 부분도 문제없이 처리한다. 예를 들어 다음처럼 작성된 비동기 API도 동일한 방식으로 테스트가 가능하다.

@app.get("/async-endpoint")
async def async_endpoint():
    return {"message": "비동기 작동 완료!"}

def test_async_endpoint():
    response = client.get("/async-endpoint")
    assert response.status_code == 200
    assert response.json() == {"message": "비동기 작동 완료!"}

🔁 반복 테스트 – 파라미터화

같은 구조의 테스트를 여러 케이스로 반복하고 싶다면 pytest.mark.parametrize를 활용할 수 있다.

import pytest

@pytest.mark.parametrize("item_id, q", [
    (1, "apple"),
    (2, "banana"),
    (3, "cherry")
])
def test_read_item_param(item_id, q):
    response = client.get(f"/items/{item_id}?q={q}")
    assert response.status_code == 200
    assert response.json() == {"item_id": item_id, "q": q}

이 방식은 여러 입력값에 대해 동일한 로직의 테스트를 반복 수행할 수 있어 생산성이 매우 높다.

🧾 테스트 실행하기

작성한 테스트는 다음 명령어로 실행한다. Windows 환경에서는 PowerShell 또는 CMD에서 아래처럼 입력하면 된다.

pytest

보다 상세한 로그를 원한다면 -v 옵션을 추가한다.

pytest -v

🧼 테스트 디렉터리 구성 팁

실무에서는 테스트 파일이 많아지므로 다음과 같이 디렉터리를 구성하는 것이 좋다.

project/
├── app/
│   └── main.py
├── tests/
│   └── test_main.py

이 구조로 테스트를 작성하면 pytest는 tests/ 디렉터리 아래의 모든 test_*.py 파일을 자동으로 인식하고 실행한다.

🎯 마무리하며

FastAPI의 테스트는 시작이 쉽고, 확장도 매우 유연하다. Pytest와 TestClient를 적절히 활용하면 API의 동작 여부를 빠르게 검증할 수 있고, 리팩토링이나 기능 추가에도 자신감을 가질 수 있다. 테스트는 코드를 믿게 만드는 유일한 방법이다. 개발 초기부터 테스트를 습관처럼 작성하는 것이 높은 품질의 백엔드를 만드는 가장 빠른 길이다.

FastAPI 공식 문서 : https://fastapi.tiangolo.com/ko/