🚀 FastAPI API 테스트 (pytest + pytest-cov)

FastAPI는 Python 기반의 비동기(Asynchronous) 웹 프레임워크로, 빠른 성능과 간결한 코드 구조 덕분에 최근 많은 개발자들이 선택하고 있습니다.
하지만 프로젝트가 커지고 API가 복잡해질수록 코드 변경 시 버그나 예외 상황이 발생할 가능성도 높아집니다.

이러한 문제를 예방하기 위해서는 FastAPI 테스트 코드 작성이 필수적입니다.
테스트 코드는 단순한 검증 단계를 넘어, 서비스 안정성과 유지보수 효율을 높이는 핵심 요소입니다.
특히 pytest를 활용하면 API 동작을 자동으로 검증하고, 데이터베이스 연동이나 비동기 처리까지 간단히 테스트할 수 있습니다.

이번 포스팅에서는 FastAPI 테스트 코드 작성 방법부터 pytest를 이용한 실행 및 커버리지(coverage) 측정 방법, 그리고 테스트 데이터의 생성·삭제를 안전하게 처리하는 방법까지 단계별로 알아보겠습니다.

🧭 목차

1. FastAPI 테스트 코드의 필요성
2. 필요 패키지 설치 및 환경 세팅
3. Pytest를 활용한 FastAPI 테스트 구조
4. 테스트 데이터의 일시적 생성 및 정리
5. 자산 API 테스트 코드 예제 분석
6. 테스트 실행 및 결과 확인
7. pytest-cov로 테스트 커버리지 확인하기
8. 마무리: 안정적인 FastAPI 개발을 위한 테스트 습관

---

🧩 FastAPI 테스트 코드의 필요성

테스트 코드는 다음과 같은 장점을 제공합니다:

• ✅ 배포 전 기능 이상 여부를 자동으로 검증
• ✅ 코드 리팩토링 시 안정성 보장

---

⚙️ 필요 패키지 설치 및 환경 세팅

테스트를 수행하기 전에 아래 명령으로 필요한 패키지를 설치합니다.

# 테스트 관련 필수 패키지
pip install pytest httpx

# DB 연동용 패키지
pip install sqlalchemy sqlmodel psycopg2-binary

# 테스트 커버리지 측정용 (선택)
pip install pytest-cov

💡 pytest-cov는 테스트 실행 중 실제 코드의 실행 비율(coverage)을 측정하여,
어떤 함수가 테스트되지 않았는지 한눈에 확인할 수 있게 도와줍니다.

---

🧱 Pytest를 활용한 FastAPI 테스트 구조

FastAPI 프로젝트는 보통 다음과 같이 구성됩니다.

project/
├── app/
│   ├── main.py
│   ├── routers/
│   └── models/
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   └── test_asset.py
└── requirements.txt

🔹 conftest.py – 공통 클라이언트 정의

# tests/conftest.py
import pytest
from fastapi.testclient import TestClient
from app.main import app

@pytest.fixture
def client():
    with TestClient(app) as c:
        yield c

TestClient는 FastAPI의 엔드포인트를 실제 서버 없이 테스트할 수 있도록 도와주는 도구입니다.

---

🧪 테스트 데이터의 일시적 생성 및 정리

테스트 환경에서 중요한 점은 “테스트용 데이터가 실제 DB를 오염시키지 않는 것” 입니다.
이를 위해 pytest.fixture를 활용하여 테스트 데이터 생성과 정리를 자동화합니다.

@pytest.fixture
def sample_asset(client):
    # 테스트용 포트폴리오 생성
    portfolio_response = client.post("/portfolios/", json={"name": "Test Portfolio", "user_id": 29})
    portfolio_id = portfolio_response.json()["id"]

    # 테스트 자산 데이터 반환
    return {
        "name": "Test Asset",
        "category": "현금",
        "amount": 1000,
        "description": "Test Description",
        "portfolio_id": portfolio_id,
        "average_price": 100.0
    }

테스트가 끝나면 FastAPI의 테스트 클라이언트가 세션을 닫고,
Docker 컨테이너 내 PostgreSQL 데이터도 롤백되므로 실제 데이터베이스에는 영향이 없습니다.

---

🧰 자산 API 테스트 코드 예제 분석

아래는 실제 사용 중인 자산(Asset) API의 테스트 코드 예시입니다.

# tests/test_asset.py
import pytest

@pytest.fixture
def sample_asset(client):
    portfolio_response = client.post("/portfolios/", json={"name": "Test Portfolio", "user_id": 29})
    portfolio_id = portfolio_response.json()["id"]
    return {
        "name": "Test Asset",
        "category": "현금",
        "amount": 1000,
        "description": "Test Description",
        "portfolio_id": portfolio_id,
        "average_price": 100.0
    }

# ✅ 자산 생성 테스트
def test_create_asset(client, sample_asset):
    response = client.post("/assets/", json=sample_asset)
    assert response.status_code == 200
    assert response.json()["name"] == sample_asset["name"]

# ✅ 자산 조회 테스트
def test_read_assets(client):
    response = client.get("/assets/")
    assert response.status_code == 200
    assert isinstance(response.json(), list)

# ✅ 자산 수정 테스트
def test_update_asset(client, sample_asset):
    create_response = client.post("/assets/", json=sample_asset)
    asset_id = create_response.json()["id"]
    updated_asset = sample_asset.copy()
    updated_asset["name"] = "Updated Asset"
    update_response = client.put(f"/assets/{asset_id}", json=updated_asset)
    assert update_response.json()["name"] == "Updated Asset"

# ✅ 자산 삭제 테스트
def test_delete_asset(client, sample_asset):
    create_response = client.post("/assets/", json=sample_asset)
    asset_id = create_response.json()["id"]
    delete_response = client.delete(f"/assets/{asset_id}")
    assert delete_response.status_code in (200, 204)

    get_response = client.get("/assets/")
    ids = [asset["id"] for asset in get_response.json()]
    assert asset_id not in ids

각 테스트는 독립적으로 수행되며,
실행 시마다 임시 데이터가 생성되고 테스트 종료 후 자동 삭제됩니다.

---

🧭 테스트 실행 및 결과 확인

테스트 실행은 간단합니다.

# 전체 모듈 테스트
pytest -v

# 일부 모듈 테스트
pytest -v backend/tests/test_asset.py

• -v : 테스트 이름과 결과를 자세히 출력
• --maxfail=1 : 첫 번째 실패 시 즉시 중단
• --disable-warnings : 경고 숨김

✅ 실행 결과 예시

모든 테스트가 PASSED라면 API가 정상적으로 동작하고 있음을 의미합니다.

---

📊 pytest-cov로 테스트 커버리지 확인하기

테스트가 통과했다고 해서 안심하긴 이릅니다.
어떤 코드가 테스트되지 않았는지를 파악하기 위해선 테스트 커버리지(coverage) 측정이 필요합니다.

🔹 1. pytest-cov 설치

pip install pytest-cov

🔹 2. 커버리지 측정 실행

# 전체 모듈 커버리지 측정
pytest --cov=app --cov-report=term-missing -v

# 일부 모듈 커버리지 측정
pytest --cov=routes.asset --cov-report=term-missing -v

옵션 설명:

• --cov=app : 커버리지를 측정할 모듈(폴더) 지정
• --cov-report=term-missing : 테스트되지 않은 코드 라인을 콘솔에 표시
• -v : 상세 모드

📈 예시 출력

위 예시에서 backend/routers/asset.py가 **74%**만 커버된 것을 확인할 수 있습니다.
즉, 특정 조건 분기(예: 예외 처리 구문 등)가 테스트되지 않았다는 의미입니다.

🔹 3. HTML 리포트 생성

좀 더 시각적으로 확인하고 싶다면 HTML 리포트를 생성할 수 있습니다.

pytest --cov=app --cov-report=html

실행 후 프로젝트 루트에 htmlcov/ 폴더가 생성되며,
브라우저에서 htmlcov/index.html을 열면 각 파일별 커버리지와 누락된 라인을 한눈에 볼 수 있습니다.

---

🧠 마무리: 안정적인 FastAPI 개발을 위한 테스트 습관

FastAPI 개발에서 테스트 코드는 선택이 아닌 필수입니다.
특히 다음 세 가지 원칙을 지키면 품질이 크게 향상됩니다.

1. 테스트용 데이터는 임시로 생성하고 테스트 후 삭제한다.
2. pytest를 통해 모든 엔드포인트를 자동화 테스트한다.
3. pytest-cov로 커버리지를 측정해 테스트 누락 구간을 점검한다.

테스트는 단순히 “코드가 잘 작동하는지 확인”하는 것이 아니라,
💡 “코드를 신뢰할 수 있게 만드는 과정” 입니다.

더 자세한 설정이나 옵션은 아래 공식 문서를 참고하세요.

🔗 참고

• pytest 공식 문서
• pytest-cov 공식 문서
• 프로젝트 개발 환경